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DF 

DU 

DEVNM 

QUOT 

WHO 


WHODO 

FINGER 

W 

USERS 

UPTIME 

ID 

LOGNAME 

UNAME 

TTY 

PS 


PWD 

CRON 


• May Set UNIX *s idea of date and time. 

Report amount of free apace on file system devices. 

Print a summary of total space occupied by all files in a hierar¬ 
chy. 

Give the device name where a specified subdirectory is resident. 
Print summary of file space usage by user id. 

Tell who's on the system. 

• List of presently logged in users, ports and times on. 

• Optional history of all logins and logouts. 

Tell who is doing what on the system. 

(•BE*) List the current users including login name, terminal 
name, login time... 

• (*BE*) Print a summary of the current activity on the system, 

including what each user is doing. 

(•BE*) Print a compact list of users who are on the system. 
(•BE*) Show how long system has been up. 

Print user and group IDs and names. 

Print login name. 

Print the current system name of UNIX. 

Print name of your terminal. 

Report on active processes. 

• List your own or Everybody’s processes. 

• Tell what commands are being executed. 

• Optional status information: state and scheduling info, prior¬ 
ity, attached terminal, what it's waiting for, size. 

Print name of your working directory. 

Clock daemon. 


1.8. Backup and Maintenance 


CLRI 

MOUNT 

UMOUNT 

MKFS 

MKNOD 

TAR 


Clear i-node. 

Attach a device containing a file system to the tree of direc¬ 
tories. Protects against nonsense arrangements. 

Remove the file system contained on a device from the tree of 
directories. Protects against removing a busy device. 

Make a new file system on a device. 

Make an i-node (file system entry) for a special file. Special 
files are physical devices, virtual devices, physical memory, etc. 

Manage file archives on magnetic tape. 

• Collect files into an archive. 

• Update DECtape archive by date. 

• Replace or delete DECtape files. 
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DUMP 


RESTOR 

VOLCOPY 

LABELIT 

.SU 

FSCK 

FSDB 

DCHECK 

1CHECK 

NCHECK 

CLR1 

INSTALL 

SYNC 

SHUTDOWN 

BADSECT 

SCRIPT 

DMESG 


• Print table of contents. 

• Retrieve from archive. 

(-0*) Dump the file system stored on a specified device, selec¬ 
tively by date, or indiscriminately. A multi-volume dump (i.e. on 
floppies) is possible. 

Restore a dumped file system, or selectively retrieve parts 
thereof. 

(—0—) Copy a file system with label checking. 

(-0-) Create initial labels for disk or tape file systems. 
Temporarily become the super user with all the rights and 
privileges thereof. Requires a password. 

(-B-) File system consistency check and interactive repair. 

File system debugger. Used to patch up a damaged filesystem 
after a crash. 

Read the directories in a file system and compare the link- 
count in each i-node with the number of directory entries by 
which it is referenced. 

Check the number of used and free blocks. List the number of 
regular files, of directories and special files. If specified, a new 
free list is constructed. 

Generate a pathname vs. i-number list. 

Peremptorily expunge a file and its space from a file system. 
Used to repair damaged file systems. 

Install commands. 

Force all outstanding I/O on the system to completion. Used to 
shut down gracefully. 

(•BE*) Close down the system at a given time. Used to notify 
users nicely when the system is shutting down. 

(•BE*) Create files to contain bad sectors. Less general than 
bad block forwarding, but better than nothing. 

(•BE*) Make a typescript of everything printed on the terminal 
during a session. 

(•BE*) Look in a system buffer for recently printed diagnostic 
messages and print them on the standard output. 


1.9. Accounting 

The UNIX System-V Accounting provides methods to collect per-process 
resource utilization data, record connect sessions, monitor disk utilization, 
and charge fees to specific logins. A set of C language programs and shell pro¬ 
cedures is provided to reduce this accounting data into summary files and 
reports. 

• At process termination, the UNIX system kernel writes one record per pro¬ 
cess to a distinct file. 











The LOGIN and INIT programs record connect sessions by writing reco J d ® 
taWetc/ilSnp Date changes, reboot., end shutdown, ere elso recorded 

in this file. 


The following list describes programs and shell-procedures of the System V 
accounting system: 


ACCTCMS 

ACCTD1SK 

ACCTDUSG 

ACCTON 

ACCTMERG 

CHARGEFEE 

CKPACCT 

MONACCT 

PRDA1LY 

RUNACCT 


(•ACC*) Command summary from per process accounting 
records. 

(•ACC*) Converts user ID. login name and number of disk blocks 
to total accounting records. 

(•ACC*) Breaks down disk usage by LOGIN. 

(•ACC*) Turns process accounting off. 

(•ACC*) Merge or add total accounting files. 

(•ACC*) Charge a number of units to a login-name. 

(•ACC*) Check total size of the accounting files, initiated by the 
clock daemon. 

(•ACC*) Creates summary files monthly. 

(•ACC*) Format a report of the previous day's accounting data. 
(•ACC*) Performs daily accumulation of connect, process, fee, 
and disk accounting. 


1.10. Communication 


MAIL 


RMAIL 

BIFF 

FROM 

PRMAIL 

LEAVE 

CALENDAR 

WRITE 

MESG 

MSGS 

CU 


Mail a message to one or more users. Also used to read and 
dispose of incoming mail. The presence of mail is announced by 
LOGIN and optionally by SH. 

• Each message can be disposed of individually. 

. • Messages can be saved in files or forwarded. 

(•UUCP*) Restricted version of MAIL for UUCP. 

(•BE*) Be notified if mail arrives and who it is from, (not longer 
supported) 

(•BE*) Show who is the sender of my mail. 

(•BE*) Print the mail which waits for you. or a specified user, in 
the ‘post office'. 

(•BE*) Remind you when you have to leave. 

Automatic reminder service for events of today and tomorrow. 
Establish direct terminal communication with another user. 
Inhibit receipt of messages from WRITE and WALL 
(•BE*) Read system messages. These messages are sent by mail¬ 
ing to the login 'msgs*. 

Call up another time-sharing system. 

• Transparent interface to remote machine. 

• File transmission. 
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UUCP 


UULOG 

UUNAME 

UUSTAT 


UUSUB 

UUTO 


UUP1CK 

EXCR 

CHECKNEWS 

INEWS 

NEWS 

POSTNEWS 

READNEWS 

RECNEWS 

RJESTART 

SEND 

UUX 

UUCLEAN 

WALL 


• Take remote input from local file or put remote output into 
local file. 

• Remote system need not be UNDC. 

File transfer between CPU’s. 

• Automatic queuing until line becomes available and remote 
machine is up. 

• Copy between to remote machines. 

• Differences, mail, etc., between two macines. 

(•UUCP*) Maintain a summary log of UUCP and UUX transac¬ 
tions. 

(•UUCP*) List the UUCP names of known systems. 

(•UUCP*) UUCP status inquiry and job control. Display status of, 
or cancel, previously specified UUCP commands, or provide gen¬ 
eral status on UUCP connections to other systems. 

(•UUCP*) Define and monitor a UUCP subnetwork. 

Public CPU to CPU command execution. Gather files from vari¬ 
ous CPUs, execute a command on a specified CPU, and send 
standard output to a file on a specified CPU. 

Accept or reject the files sent by UUTO. Looks somewhat like 
MAIL. 

(*NC*) Ruii a program on another system. 

(•UUCP*) Check to see if user has news. 

(•UUCP*) Submit news articles. 

(•UUCP*) Print news items. 

(•UUCP*) Submit news articles. 

(•UUCP*) Read news articles. 

(•UUCP*) Receive unprocessed articles via mail. 

(*RJE*) RJE-status report and interactive status console. 

(*RJE*) Gather files and submit RJE-jobs. 

(•UUCP*) Unix to unix command execution. 

(•UUCP*) Uucp spool directory clean-up. 

Write to all users. 


1.11. Basic Program Development Tools 


Some of these utilities are used as integral parts of the higher level languages 
described in section 2. 

AR Maintain archives and libraries. Combines several files into one 

for housekeeping efficiency. 

• Create new archive. 

• Update archive by date. 

• Replace or delete files. 

• Print table of contents. 

• Retrieve from archive. 







A68 


LIBRARY 


CURSES 

ADB 


OD 


XD 

LD 


A fast M68000-Assembler. 

• Creates object program consisting of 

code, possibly read-only 
initialized data 
uninitialized data. 

• Object code normally includes a symbol table. 

• 

The basic run-time library. These routines are used freely by 
all software. 

• Buffered character-by-character I/O. 

• Formatted input and output conversion (SCANF and PRINTF) _ 
for standard input and output, files, in-memory conversion. 

• Storage allocator. 

• Time conversions. 

• Number conversions. 

• Password encryption. 

• Quicksort. 

• Random number generator. 

• Mathematical function library, including trigonometric func¬ 
tions and inverses, exponential, logarithm, square root, 
bessel functions. 

(•BE*) Library of screen functions which allows screen updating 
(with user input) and cursor motion optimization. 

(-0-) Interactive debugger. 

• Postmortem dumping. 

• Examination of arbitrary files, with no limit on size. 

• Interactive breakpoint debugging with the debugger as a 
separate process. 

• Symbolic reference to local and global variables. 

• Stack trace for C programs. 

• Output formats: 

1-, 2-, or 4-byte integers in hex, octal 

or decimal 

single and double floating point 
character and string 
disassembled machine instructions 

• Patching. 

• Searching for integer, character, or floating patterns. 

• Handles separated instruction and data space. 

Dump any file. Output options include any combination of octal 
or decimal by words, octal by bytes, ASCII, opcodes, hexade¬ 
cimal. 

• Range of dumping is controllable. 

Hexadecimal file dump. 

Link edit. Combine relocatable object files. Insert required 
routines from specified libraries. 
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LORDER 

NM 

SIZE 

STRIP 

TIME 

PROF 


MAKE 


ERROR 


HELP 

NOTES 

PACK 

RANL1B 

REGCMP 

TIMEX 


• Resulting code may be sharable. 

• Resulting code may have separate instruction and data 
spaces. 

Places object file names in proper order for loading, so that 
files depending on others come after them. 

Print the namelist (symbol table) of an object program. Pro¬ 
vides control over the style and order of names that are 
printed. 

Report the core requirements of one or more object files. 

Remove the relocation and symbol table information from an 
object file to 6ave space. 

Run a command and report timing information on it. 

Construct a profile of time spent per routine from statistics 
gathered by time-sampling the execution of a program. 

• Subroutine call frequency and average times for C programs. 
Controls creation of large programs. Uses a control file specify¬ 
ing source file dependencies to make new version; uses time last 
changed to deduce minimum amount of work necessary. 

• Knows about CC, PASCAL, YACC, LEX etc. 

(•BE*) Analyze and disperse compiler error messages. 

• Knows about error messages produced by MAKE. CC, CPP, AS, 
LD. LINT. PC. F77. 

• Attempts to determine which language processor produced 
each error message. 

• Determines source file and line number to which the error 
message refers. 

• Determines if the error message is to be ignored, or not. 

• Inserts the error message into the source file as comment 
Ask for help. 

A news system. 

(-V7-) Packs or unpacks many files <—> one. 

(-V7-) Convert archives to random libraries. 

Regular expression compile. 

Time a command; report process data and system activity. 









1.12. UNIX Programmer's Manual 


MANUAL 


MAN 

MAN 


CATMAN 

apropos 

WHATIS 


Machine-readable version of the UNIX Programmer’s Manual. 

• System overview. 

• All commands. 

• All system calls. 

• All subroutines in C and assembler libraries. 

• All devices and other special files. 

. Formats of file system and kinds of files known to system 
software. 

• Boot and maintenance procedures. 

Print specified manual section on your terminal. 

(•BE*) Give information from the on line programmers' manual. 

• Gives all commands whose description contains any of a 
specified set of keywords. 

• Attempts to locate manual sections related to a specified list 
of files. 

• Formats a specified set of manual pages. 

(•BE*) Create the preformatted versions of the on-line manuals. 
(•BE*) Show which manual sections contain instances of any of 
the given keywords in their title. 

(•BE*) Look up a given command and give the header line from 
the manual section. 


1.13. Computer Aided Instruction 

LEARN A program for interpreting CAI scripts, plus scripts for learning 

about UNIX by using it. 

• Scripts for basic files and commands, editor, advanced files 
and commands. EQN, MS macros. C programming language. 
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2. Languages 
2.1. The C Language 

CC (-0-) Compile and/or link edit programs in the C language. The 

UNIX operating system, most of the subsystems and C itself are 
written in C. For a full description of C. read ‘The C Program¬ 
ming Language", Brian W. Kemighan and Dennis M. Ritchie, 
Prentice-Hall, 1978. 

• General purpose language designed for structured program¬ 
ming. 

• Data types include character, integer, float, double, pointers 
to all types, functions returning above types, arrays of all 
types, structures and unions of all types. 

• Operations intended to give machine-independent control of 
full machine facility, including to-memory operations and 
pointer arithmetic. 

• Macro preprocessor for parameterized code and inclusion of 
standard flies. 

• All procedures recursive, with parameters by value. 

• Machine-independent pointer manipulation. 

• Object code uses full addressing capability of the M68000. 

• Runtime library gives access to all system facilities. 

• Floating point arithmetic realized by software. 

• Definable data types. 

• Block structure 

LINT Verifier for C programs. Reports questionable or nonportable 

usage such as: 

Mismatched data declarations and procedure 
interfaces. 

Nonportable type conversions. 

Unused variables, unreachable code, no-efTCect 
operations. 

Mistyped pointers. 

Obsolete syntax. 

• Full cross-module checking of separately compiled programs. 

CB A beautifier for C programs. Does proper indentation and 

placement of braces. 

CPP The C language preprocessor. Also used by F77 and Pascal. 

INDENT (-V-) Indent and format a C program source. 
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2.2. Fortran 
F77 


RATFOR 


STRUCT 


A full compiler for ANSI Standard Fortran 77. 

• Compatible with C and supporting tools at object level. 

• Optional source compatibility with Fortran 66. 

• Free format source. 

• Optional subscript-range checking, detection of uninitialized 
variables. 

. all widths of arithmetic: 2- and 4-byte integer; 4- and 8-byte 
real; 8- and 16-byte complex. 

Ratfor adds rational control structure like C to Fortran. 

• Compound statements. 

• If-else, do, for, while, repeat-until, break, next statements. 


• Symbolic constants. 

• File insertion. 

• Free format source 

• Translation of relational like >, >=• 

• Produces genuine Fortran to carry away. 

• May be used with F77. 

Converts ordinary ugly Fortran into structured Fortran (i^e. 
Ratfor). using statement grouping, if-else, while, for, repeat 

until. 

(-V7-) Extended Fortran Language. 


EFL 
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2.3. Pascal 

PC (*PAS*) Compile and/or link programs in the PASCAL 68000 

language. 

PASCAL 68000 is an extended implementation of the PASCAL 
language. Specifically PASCAL 68000 complies almost com¬ 
pletely with the requirements of the ISO standard proposal for 
PASCAL. Some of the features of PASCAL 68000 are 

• General purpose language 

• Block oriented language 

• Strong type checking 

• Variety of data structures: 

simple types, arrays, records, 
sets, files, pointers, strings 

• Conformant arrays 

• Various control statements 

• Predefined procedures and functions 

• Seperate compilation of modules 

• Import and export of variables.procedures and functions 

• Linking C, FORTRAN or assembler modules to PASCAL 68000 
modules 
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2.4. Snobol 


SNO 


(•SNO*) Is an implementation of the SNOBOL language (espe- 
einllv the SPITBOL version). Its unusual support for string, list 
ail datable mediation mikes SNO a powerful tool for several 

.^0 has some of the best features of Basic and Lisp: It is 
interactive, has -rubber memory' for strings, lists and associ- 
ative tables, and finally it is easy to learn. 

• SNO is qualified for the following applications*. 

text editing jobs 

small interactive data bases 

small translators: mini-languages, macros... 

• Preprocessor snif 


2.5. Other Algorithmic Languages 


BS 


DC 


BC 


BASIC 

FACTOR 


• compiler /interpreter for modest-siied programs A descon- 
dMt of Basic and SNOBOL 4 with e little C language thrown in. 

. Statements from console execute immediately. 

. Statements from a file compile for later execution (by 

default). 

• Line-at-a-time debugging. 

• Many builtin functions. 

Interactive programmable desk calculator. Has named storage 
locations as well as conventional stack for holding integers or 

programs. 

• Unlimited precision decimal arithmetic. 

• Appropriate treatment of decimal fractions. 

• Arbitrary input and output radices, in particular binary, 
octal, decimal and hexadecimal. 

• Reverse Polish operators: 

+ -• / 

remainder, power, square root, 
load, store, duplicate, clear, 
print, enter program text, execute. 

A C-like interactive interface to the desk calculator D . 

• All the capabilities of DC with a high-level syntax. 

• Arrays and recursive functions. 

. Immediate evaluation of expressions and evaluation of func¬ 
tions upon call. 

• Arbitrary precision elementary functions: exp. sin. cos. atan. 

• Go-to-less programming. 

Basic Interpreter. 

(-V-) Factor a number. 








IFPROLOG (*PRO*) The prolog interpreter system. 


2.6. Macroprocessing 


M4 A genera] purpose macroprocessor. 

• Stream-oriented, recognizes macros anywhere in text. 

• Syntax fits with functional syntax of most higher-level 
languages. 

• Can evaluate integer arithmetic expressions. 


2.7. Compiler-compilers 


YACC An LR(l)-based compiler writing system. During execution of 

resulting parsers, arbitrary C functions may be called to do 
code generation or semantic actions. 

• BNF syntax specifications. 

• Precedence relations. 

• Accepts formally ambiguous grammars with non-BNF resolu¬ 
tion rules. 

LEX Generator of lexical analyzers. Arbitrary C functions may be 

called upon isolation of each lexical token. 

• Full regular expression, plus left and right context depen¬ 
dence. 

• Resulting lexical analysers interface cleanly with YACC 
parsers. 
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3. Text Processing 
3.1. Document Preparation 


ED 


MED 


EX 


Interactive context editor. Random access to all lines of a file. 

. Find lines by number or ££•*2525 

rrecu4 h «p C e l UUcns°of Xe'se'tnsirucis. beginning ol 
line, end ofline. 

. Add. delete, change, copy, move or join lines. 

• Permute or split contents of a line. 

. Replace one or all instances of a pattern within a line. 

. Combine or split files. 

. Escape to Shell (commend language) during 
. Do eny of ebove operations on every pattern-selected line in 

a given range. 

Dritinnal encryption for extra security. 

(•MED*) This editor alios you to edit a Me using the»c«“ “ d 
the cursor keys somewhat like paper, pend and eraser. 

. Add. delete, change, copy lines. 

• Split, concatenate lines. 

• Find lines by number or pattern. 

• Manage previous defined rectangles. 

• Switch to another file. 

•. install 'windows for working simultaneously with different 
files. 

. Escape to Shell during editing. , ... ™ 

(•BE*) The Une oriented^text edhor is^a “£”'tive display 

functionVlEWand the family of editors: EX. EDIT. VI. 

• Find lines by number or pattern. 

. Add. delete, change, copy, move or join lines. 

• Permute or split contents of a line. 

. Replace one or all instances of a pattern within a line. 

• Combine or split files. 

• Switch to the location of a ‘tag’. 

• Enter intraline editing. 

. Reverse the effects of the last command. 

• Escape to Shell during editing. 

• Indent automatically. 

*. rempi":"th« buffer in case o, hangups or crashes. 
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EDIT 


VI 


VIEW 

CTAGS 

PTX 

SPELL 

CRYPT 

HYPHEN 

MKSTR 


• Read and execute commands from a specified file. 

• Simulate an intelligent terminal on a dumb terminal. 

(•BE*) A small version of EX. Avoids some of the complexities of 
EX to provide an environment for new and casual users, (not 
longer supported) 

• Find lines by number or pattern. 

• Add, delete, change, copy or move lines. 

• Replace a pattern in a line. 

• Add the contents of a file. 

• Reverse the effects of the last command. 

• Escape to Shell. 

• Attempt to recover the buffer in case of hangups or crashes. 

(•BE*) The screen oriented editor VI is based on EX (see above). 
Additional attributes: 

• Numerous commands for file manipulation, 
i.e. edit file containing the tag 'tag* 

at the first line of 'tag' 

• Extensive command set for scrolling, paging and cursor 
motion. 

i.e. move to the end of line 

move to the begin of the next word 

• Various units of text can be handled: words, sentences, sec¬ 
tions. 

i.e. duplicate sentence 
delete word 

• Searching for strings by a set of different conditions, 
i.e. matches any character between *x' and *y* 

matches the end of a word 

• Definition of macros for saving time by typing commands. 

• Escape to the line oriented editor EX. 

(•BE*) Interactive display function. Works like the VI - but with 
read-only files, (not longer supported) 

(•BE*) Make a tags file for EX from the specified C, PASCAL and 
FORTRAN sources. A tags file gives the locations of specified 
objects (in this case functions) in a group of files. 

Make a permuted (key word in context) index. 

Look for spelling errors by comparing each word in a document 
against a word list. 

• 25,000-word list includes proper names. 

• Handles common prefixes and suffixes. 

• Collects words to help tailor local spelling lists. 

Encrypt and decrypt files for security. 

Find hyphenated words. 

(•BE*) Used to create a file of error messages by massaging C 
source code. 
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XSTR 


DICTION 


EXPLAIN 

STYLE 


CUT 

DBADD 

EMACS 

PREP 

REFER 


. Places ell error messages Irom a C source file in a specified 

. Keys on the string 'errorf to process the error messages to 

the message file. . 

. The copy oi the C source file contains pointer into the mes 

sage file to retrieve the error message. . 

(•BE*) Extract strings from C programs to implement shared 

constant strings. , Mr . c nf „ 

. Maintains a file into which strings of component parts of a 
large program are hashed. 

. The strings are replaced with references to the common 
area. 

(•BE*) Find wordy sentences in a document. 

. Finds all sentences that contain phrases from a data base of 
bad or wordy diction. 

• The user may supply his own pattern file. 

(•BE*) Interactive thesaurus for the phrases found by diction. 
(•BE*) Analyze surface characteristics of a document. 

• Reports on 

readability 

sentence length and structure 
word length and usage 
verb type 
sentence openers 

. Options to locate sentences with certain characteristics. 
(-V-) Cut out selected fields of each line of a file. 

(•EMAC*) Add entry to an Emacs data base. 

(•EMAC*) A screen editor. 

Prepare text for statistical processing. 

Find and insert literature references in documents. 
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3.2. Document Formatting 


TROFF 

NROFF Advanced typesetting. TROFF drives a Graphic Systems photo¬ 

typesetter; NROFF drives ascii terminals of all types. TROFF and 
NROFF style is similar to ROFF (not available on HUNK), but 
they are capable of much more elaborate feats of formatting 
when appropriately programmed. TROFF and NROFF accept the 
same input language. 

• All ROFF capabilities available or definable. 

• Completely definable page format keyed to dynamically 
planted ••interrupts" at specified lines. 

• Maintains several separately definable typesetting environ¬ 
ments (e.g., one for body text, one for footnotes, and one for 
unusually elaborate headings). 

• Arbitrary number of output pools can be combined at will. 

• Macros with substitutable arguments, and macros invocable 
in mid-line. 

• Computation and printing of numerical quantities. 

• Conditional execution of macros. 

• Tabular layout facility. 

• Positions expressible in inches, centimeters, eras, points, 
machine units or arithmetic combinations thereof. 

• Access to character^width computation for unusually 
difficult layout problems. 

• Overstrikes, built-up brackets, horizontal and vertical line 
drawing. 

• Dynamic relative or absolute positioning and size selection, 
globally or at the character level. 

• Can exploit the characteristics of the terminal being used, 
for approximating special characters, reverse motions, pro¬ 
portional spacing, etc. 

The Graphic Systems typesetter has a vocabulary of several 102-character 
fonts (4 simultaneously) in 15 sizes. TROFF provides terminal output for 
rough sampling of the product. 

NROFF will produce multicolumn output on terminals capable of reverse line 
feed, or through the postprocessor COL 

High programming skill is required to exploit the formatting capabilities of 
TROFF and NROFF, although unskilled personnel can easily be trained to 
enter documents according to canned formats such as those provided by MS 
below. TROFF and EQN are essentially identical to NROFF and NEQN so it is 
usually possible to define interchangeable formats to produce approximate 
proof copy on terminals before actual typesetting. The preprocessors MS and 
TBL are fully compatible with TROFFand NROFF. 

MS The standardized manuscript layout package of V7 for use with 

NROFF or TROFF. This document was formatted with MS. 
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MM 


ME 

COLCRT 

MMCHEK 

MMT 

VTKOFF 

LTROFF 

EQN 


NEQN 


TBL 


• Page numbers and draft dates. 

• Automatically numbered subheads. 

• Footnotes. 

• Single or double column. 

• Paragraphing, display and indentation. 

• Numbered equations. 

The standardized manuscript layout package of System III for 
use with NROFF or TROFF. Some features different from the MS 
macro package: 

• Table of contents. 

• Static and Floating displays. 

• Special formatting macros for preparing memoranda and 
released papers.. 

(•BE*) Package from Berkeley 4.1 bsd for formatting technical 
papers with NROFF or TROFF. Easy to learn. 

(-V-) Filter nroff output for CRT previewing. 

(-V-) Check usage of mm macros and eqn delimiters. 

(-V-) Typeset documents, view graphs, and slides. 

(•BE*) Troff for raster printer/plotter. 

(•TSP*) Troff for CANON laser beam printer. Ltroff accepts the 
same input language as troff. 

A mathematical typesetting preprocessor for TROFF. Translates 
easily readable formulas, either in-line or displayed, into 
detailed typesetting instructions. 

. Automatic calculation of size changes for subscripts, sub- 
subscripts, etc. 

. Full vocabulary of Greek letters and special symbols, such as 
•gamma’. •GAMMA’, ’integral’. 

. Automatic calculation of large bracket sizes. 

• Vertical ’’piling** of formulae for matrices, conditional alter¬ 
natives, etc. 

• Integrals, sums, etc., with arbitrarily complex limits. 

• Diacriticals: dots, double dots, hats, bars, etc. 

• Easily learned by nonprogrammers and mathematical typ¬ 
ists. 

A version of EQN for NROFF: accepts the same input language. 
Prepares formulas for display on any terminal that NROFF 
knows about, for example, those based on Diablo printing 
mechanism. 

. Same facilities as EQN within graphical capability of termi¬ 
nal. 

A preprocessor for NROFF/TROFF that translates simple 
descriptions of table layouts and contents into detailed 
typesetting instructions. 

• Computes column widths. 
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GREEK 


COL 

DEROFF 

CHECKEQ 

VFONT1NFO 

SOELIM 

CHECKNR 


PTI 

FMT 


• Handles left- and right-justified columns, centered columns 
and decimal-point alignment. 

• Places column titles. 

• Table entries can be text, which is adjusted to fit. 

• Can box all or parts of table. 

Fancy printing on Diablo-mechanism terminals like DASI-300 
and DASI-450, and on Tektronix 4014. 

• Gives half-line forward and reverse motions. 

• Approximates Greek letters and other special characters by 
overstriking. 

Canonicalize files with reverse line feeds for one-pass printing. 
Remove all TROFF commands from input. 

Check document for possible errors in EQN usage. 

(•BE*) Inspect and print out information about unix fonts. 
(•BE*) Eliminate .so’s from nroff input. 

(•BE*) Check NROFF/TROFF files. 

• Knows about US and ME macro packages. 

• Checks unknown commands. 

• Checks mismatched opening and closing delimiters in case of 

macros which always come in pairs 
font changes 
size changes 

(•BE*) Interpret a stream from the standard output of TROFF as 
it would act on the typesetter. 

(•BE*) Simple text formatter. 

• Produces an output with lines as close to 72 characters as 
possible. 

• Spacing at the beginning of input lines and blank lines are 
preserved. 
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4. Information Handling 


SORT 


TSORT 

UN1Q 


TR 


D1FF 


SDIFF 

COMM 

JOIN 

GREP 


LOOK 

WC 

SED 


AVTK 


sort or merge ASCII Wee line-by-line. No limit on input sire. 

• Sort up or down. 

c n «i lexicographically or on numeric ey. 

order. 

. Optionally suppress duplicate data. 

Tooological sort - converts a partial order into a total order. 

• Mav give redundancy count for each line. 

Do one-to-one cherecter tronslaUon according to an arbitrary 

r May coalesce selected repeated characters. 

• Mav delete selected characters. . . 

Report line changes, additions and deletions necessary br g 

rC'produTan'editor script to convert one «e into 

Combine tv«f files 1 by joining records that have identical keys. 
Print all lines in a file that satisfy a pattern. 

• May print all lines that fail to match. 

• May print count of hits. 

. Wav Drint first hit in each file. 

. . eorted file for lines with specified prefix. 

Court the Unes "words" (blanh-separated strings) and charac- 

ters in a file. oerform a sequence of edit* 

mg C ope«tions on'ea'ch Une of an input stream of unbounded 

l en Unes may be selected by address or range of addresses. 

• Control flow and conditional testing. 

• Multiple output streams. 

satisfies the pattern. 


( 
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BFS 


• Patterns include regular expressions, arithmetic and lexico¬ 
graphic conditions, boolean combinations and ranges of 
these. 

• Data treated as string or numeric as appropriate. 

• Can break input into fields; fields are variables. 

• Variables and arrays (with non-numeric subscripts). 

• Full set of arithmetic operators and control flow. 

• Multiple output streams to files and pipes. 

• Output can be formatted as desired. 

• Multi-line capabilities. 

Big file scanner. Similar to ED, except it is read-only and 
processes larger files. Useful for identifying sections of a large 
file where CSPLIT can be used to divide it. 

• Maximum file size is 1024-K bytes. 

• Scans actual file, not a copy. 

• All ED address expressions are supported. 

• Regular expression processing. 

• Most ED commands operate. 

• Many additional commands. 


PWCK 

GRPCK 

CREF 

XREF 

5. Graphics 


Scan the password file and note inconsistencies.. 

Verify entries in the group file. 

Make a cross-reference listing of an assembler or C program. 

(•PAS*) Create a cross reference listing from a C or Pascal pro¬ 
gram. 


The programs in this section are predominantly intended for use with Tek¬ 
tronix 4014 storage scopes. 


GRAPH 


SPLINE 

TPLOT 


PLOT 

TC 

TK 


Prepares a graph of a set of input numbers. 

• Input scaled to fit standard plotting area. 

• Abscissae may be supplied automatically. 

• Graph may be labeled. 

• Control over grid style, line style, graph orientation, etc. 

Provides a smooth curve through a set of points intended for 
GRAPH. 

A set of filters for printing graphs produced by GRAPH and 
other programs on various terminals. Filters provided for Tek¬ 
tronix 4014, DASI terminals, Versatec printer /plotter. 

Graphics filters. 

(-V7-) Phototypesetter simulator. 

(-V7-) Paginator for the Tektronix 4014. 
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6. Source Code Control System SCCS 

sees is a collection Of to files of teX ( W 

cMv . th. *““"4^:;';;°' n „ sccs m „ a „d change ot exist- 

("sCCS*) Change the delta commentary of an SCCS delta. 

(•SCCS*) Combine SCCS deltas. 

(•SCCS*) Make a delta (change) to an SCCS file. 

(•SCCS*) Create an ASCII text file 

(•SCCS*) Print an SCCS file. 

Remove a delta from an SCCS file. 

( ( . S S CCS-) inform th. user of any impending deltas to a named 

(.SCCS-)’Compare two versions of an SCCS file and generate a 

list Of differences. erre 

r*«;rcs*l Undo a previous GET of an SCCS file. 

.SCCS- DeterJn. if a specified file is an SCS ftle me.tm, 
characteristics specified by the argument list. 

(•SCCS*) Identify SCCS files. 


ADMIN 

CDC 

COMB 

DELTA 

GET 

PRS 

RMDEL 

SACT 

SCCSD1FF 

UNGET 

VAL 

WHAT 


7 . Novelties, Games, and Things That Didn’t Fit Any Where Use 


arithmetic 
backgammon 
banner 

BCD 

CAL 

fcookie 

QUIZ 

STARTREK 

UNITS 

WUMP 

FISH 

HANGMAN 

HANG 

TWINKLE 1 
TW1NKLE2 
WORM 


Speed and accuracy test for number facts. 

A player of modest accomplishment. 

Print output in huge letters. 

Converts ascii to card-image form. 

^^ol^ "^Ucauon. Undud 

Test your'knowledg^of Shakespeare. Presidents, capitals, etc. 

Strategy game. Destroy the klingons.^ ^ ^ 
toowfaboutZndreds'of uniU. For example, how many km/..= 

Hunt the*wumpmt thrilling search in a dangerous cave. 

”. E .) Childrens’ card guessing game, (not longer supported) 

(.be*) word guessing games. Uses the dictionary supplied with 
SPELL. 

f*BE*l Milky way on the screen, (not longer supported) 

( ( 4e-) Uad the worm to random points, (not longer supported) 
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WORMS 

BACK 

BJ 

CRAPS 

MOO 

REVERSI 

ROGUE 

* TTT 
WUMP 
HUP 
TRUE 
FALSE 


supported) 6 ™* W ° rmS runnin 8 around on screen, (not longer 

The game of backgammon. 

The game of black jack. 

The game of craps. 

Guessing game. 

Reversi, a game of dramatic reversals. 

ever'seen ® un ^ eons Doom - the biggest game you 've 
Tic-tac-toe. 

The game of hunt-the-wumpus. 

(-0-) Ring the terminal bell, (not longer supported) 


Provide truth values. 
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Setting up MUNIX Version 1.5/02 


Unix grows at a considerable speed, getting more and more complex. Moreover, 
systems by PCS come in a wide range of hardware configurations. These factors 
together make the setting up process a nontrivial task. It is complicated to 
describe this process in a linear fashion. We hope we made the process a bit 
easier to follow by writing it down as an '’algorithm*' with conditionals and 
(phooey) gotos. 


If you have a new system, where the disks have been configured for 1.5 by 
PCS. go to label NEWSTAND. 

If you have an old system with pre 1.5 software, go to SAVEOLD, else go to 
READV1.5 


SAVEOLD , 

Save your own files on a backup medium. When you read the files in later, 
you will read them probably onto a 1024 byte filesystem. In addition, save 
several system files. The first set of system files should be saved for later 
examination. They will not be copied back! The second set is saved and 
later copied back. 


The following files are in the first set, which is not copied back, but must be 
inspected, if you have introduced local additions or changes. 


File 

Reason 

/.profile 

your file system names 

/etc/fstab 

/etc/group 

your groups 

/etc/keycap 

your keyboard capabilities 

/etc/passwd 

/etc/profile 

/etc/rc 

your user entries 

/etc/termcap 

your terminal capabilities 

/etc/ttys 

your terminal names 

/etc/ttytype 

your terminal types and speeds 

/usr/lib/crontab 

your local additions 

/usr/sys/conf.h 
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setup 


The following files must be saved to be copied back later: 


File 

Reason 

/tmp/spool/* 

NEWS 

/usr/lib/news/active 

NEWS 

/ usr /lib / news/history 

NEWS 

/usr/lib / news/history .dir 

NEWS 

/usr /lib /news /history .pag 

NEWS 

/usr/lib/news/net.recording 

NEWS 

/usr /lib / news /recording 

NEWS 

/usr/lib/news/sys 

NEWS 

/usr/lib/uucp/L-devices 

UUCP 

/usr/lib/uucp/L.sys 

UUCP 

/usr/local/* 

your own commands 


If you had other local commands in /bin or /usr/bin, move them to /usr/local! 


READV1.5 

If the new release is on a set of floppies, go to READFLOPPY. 


READTAPE 

You have to read the new version from tape or cartridge. You got two or 
more tapes or streamer cartridges. The first tape or cartridge contains the 
standalone programs and a minimal root file system in dump format (see 
dump (5)), the other tape(s) or cartridge(s) contain additional files in cpio 
format. The first tape or cartridge starts with four standalone programs, 
i.e. boot (a boot program), check (a disk formatter program), mkfs (to 
make a new filesystem), and restor (to restore from a dump tape). A dump 
of a minimal root file system follows. Additional filesets are on the second 
tape. 


You start by loading the boot program from the tape or streamer car¬ 
tridge. After that, the boot program can be used to load more programs 
from the tape or other medias. The minitor must prompt you with a 

- Power on (if you want to boot from tape, set the magtape drive to 
ONLINE) 

- hit any key 

the Minitor prompts with 
what ? 


Your input 

Machine Reaction 

rt or rs 

select tape or streamer 

/ 

reads in first file (boot program) 

g 

starts boot program, prompts for new program 
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setup 


If your disks are not hardware formatted, or if they have not been checked 
for bad blocks, go to FORMAT, else go to MKFS 

FORMAT 

The second program on the tope, check, formats the disks and checks 
them for bad blocks. If bad blocks are found, they are recorded in a bad 
sector table, together with a replacement block. Thus, the disk appears 
100% ok. 


Your Input 

Machine Reaction 

tm(0,l) or 

load second file (check) from tape 

st(O.l) 

or streamer 


check program starts 


The check program will ask for a device name. You enter rl, hi, rm or hk, 
and the disk number in brackets. The disk number is the physical disk 
number, as interpreted by the controller. You may e.g. have a Fujitsu 80 Mb 
disk, which is "seen" by the controller as three physical disks, 2 RK07s and 
1 RK06. So you would enter the names hk(0), hk(l) and hk(2). The disk 
number must not be confused with major or minor device numbers, or with 
device names, /dev/hkl is not the same as hk(l) for the check program! 

Then you are asked for a command. You enter "f" to format the disk, "b" 
to make a bad sector scan, and "q" to quit. You repeat this sequence for 
all disks, and then enter "exit" to exit the check program. 

MKFS 

The third program on the tape is the mkfs program. It is used to make a 
new root file system. The boot program is still loaded and prompts you for 
a new program: 


Your input 

Machine Reaction 

Comment 

tm(0,2) or 
st(0,2) 

loads mkfs program 

mkfs prompts with "file sys size:" 


8000 or 


enter root fs size for 

9600 or 

9636 

mkfs prompts with "file system?" 

rl, rm or hk resp. 

rl(0,0) or 


enter your type of 

rm(0,0) or 
hk(0.0) 


root device 


8000 blocks are used for RL, 9600 for RM and 9636 for HK. 
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setup 


RESTOR 

Now you load the restor program, 
newly formatted disk. 


and read the root file system onto the 


- hit 1N1T key 
the Mini tor prompts with 


Your input 

Machine Reaction 

Comment 

rt or rs 

select tape or streamer 


/ 

reads in first file (boot program) 


e 

starts boot program, 
prompts for new program 


tm(0,3) or 
st(0,3) 

loads restor program 

restor prompts "Tape?*' 

the root file system is the 

tm(0,4) or 

st(0.4) 

restor prompts "Disk?" 

4th file on the tape 

rl(O.O) or 
rm(O.O) or 
hk(O.O) 

enter the type of disk 

restor prompts 
"last chance before 
scribbling on disk" 

for the root file system 

Hit <Retum> 

a few seconds will pass 

wait until restor prompts 

before the tape or the 
streamer cartridge moves 

with "Exit called" 


go to LOADAUNIX. 
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setup 


HEADFLOPPY 

You have a bunch of floppies, which must be read in one by one. One floppy 
contains the standalone programs, the others contain a root filesystem in 
dump format and additional files in cpio format for the usr filesystem. The 
disk is emulated as an RL02. Insert the floppy with standalone programs 
into drive 0 and start the boot program. 


Your input 

Machine Reaction 

rx 

select floppy as boot device 

/boot 

reads in boot program 

e 

starts boot program, 

prompts for new program 


Formatting and checking the disks is analogous to the sequence of actions 
described at READTAPE. So we just give the commands and a short descrip¬ 
tion here. 


Your input 

Machine Reaction 

Comment 

rx(2,0)check 

boot prompts for a program 
load disk check/format program 


rl(O) 

asks for devname(unit) 
check/format rl disk 0, 


f 

asks for command 

format disk 

y 


answer each question 
with y for yes 

y 

formats disk, 


b 

bad sector scan 


q 

quit actions for rl(0) 


rl(l) 

check/format rl disk 1, 


f 

asks for command 

format disk 

y 


answer each question 

w 

7 

formats disk, 

with y for yes 

b 

bad sector scan 


q 

quit actions for rl(l) 


exit 

exit check program 


rx(2,0)mkfs 

load mkfs from floppy. 


8000 

asks file system size 

root filesystem size 

rl(O.O) 

makes new file system, exits 


rx(2.0)restor 

load restor program, 


asks for 'Tape" 
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setup 


Change floppy to #1 of root file system 


Your input 

Machine Reaction 

rx(2.0) 

'Tape" is the floppy drive 
asks for "Disk" 

rl(O.O) 

"Disk" is the RL drive 

"last chance before 
scribbling on disk" 

press "return" key 

reads in first floppy, "mount volume 2..." 


Change floppy to #2 of root file system and press return. Repeat this with 
floppy #3. #4 and so on. Eventually, the restor will be done. 

LOADAUNIX BLi t , , , . 

You now have a root file system. This contains a umx kernel, /unix. 

configured for your system, and a unix kernel, /aunix. that can run on a 
variety of disks. Load /unix with the minitor or with the boot program from 
the root file system and start it. If you have a minitor with autoload capa¬ 
bility, /unix will be loaded automatically after hitting the INIT key, other¬ 
wise, follow the description below. 


Your Input 

Machine Reaction 

Comment 

Hit INIT key 

Minitor prompts with 
if not, press RETURN until 
Minitor prompts with "." 


hk or 

select disk type 

rm or 
rl 


(default is HK) 

/unix 

load /unix 


g 

start /unix 



If you load /aunix instead of /unix, aunix will ask some questions before it 
comes up. When the kernel asks you whether it shall go into multi user 
mode, answer n for no. 


Your Input _Machine Reaction_ 

going Multi-user mode ? (y/n): 
n 

to go multi-user type "init 2". 
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setup 


SETDATE 

Set the correct date with the command 
date mmddhhmmyy 


mm 

is the 

month number 

dd 

is the 

day number in the month 

hh 

is the 

hour number (24 hour system) 

mm 

is the 

minute number 

yy 

is the 

last two digits of the year 


For example: date 0415093084 sets the date to Apr 15, 1984, 9:30 pm. 
This will be usefull if you want to make a new kernel. 


MAKEDEV 

Look at the entries in directory /dev. The special files in 
should reflect your hardware configuration. If not, call 
needed entries. 


this directory 
make for the 


Next you must make additional filesystems on the disk, first of all the sys¬ 
tem for /usr. The following commands make a default /usr filesystem: 


Device 

Command 

RL: 

mkfs /dev/rrl2 20380 

HK: 

mkfs /dev/rhk2 53636 

RM: 

mkfs /dev/rrm2 105120 


For HK and RM. the logical disk partion for the swap space (minor unit 1) 
can be partly used for a /trap filesystem, if the main memory has not more 
than 1 megabyte. E.g. for HK, you can use 4000 blocks of the 8910 blocks 
of the swap space for a /trap filesystem. The 8910 blocks would be divided 
into the /tmp area from 0 to 3999, and the swap space proper from 4000 to 
8909. Both the special files for /tmp (/dev/tmp) and for swap (/dev/swap) 
would have minor unit number 1. For swap, we would hove SWPLO = 4000 
instead of 0. and NSWAP = 4910 instead of 8910, in /usr/sys/conUi. 

After the mkfs for all filesystems, mount them on their respective direc¬ 
tories and read the second tape or cartridge with the /usr files. Make sure 
you are in the / directory (cd /). Use cpio with the options -iBvmd on the 
tape or -iSvmd on the streamer or -ivmd on the floppy: 
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Device 

Commands 

streamer: 

cd / 

cpio -iSvmd </dev/nrstO 

tape: 

cd / 

cpio -iBvmd </dev/nrmtO 

floppy: 

cd / 

cpio -ivmd < /dev/rrx2 


Repeat as many times as there are filesets listed on your distribution 
media. 

NEWKERNEL 

You may configure a Unix kernel specially adopted to your hardware. This 
is best done by calling /etc/newconf in directory /usr/sys. followed by 
make. You may wish to look at the files /usr/sys/conf.h, /usr/sys/c.c and 
/usr/sys/name.c before starting make, and edit them if you want to devi¬ 
ate from the standard values supplied there. After the make, you have a 
new kernel /nunix, which you should try out, as described in newconf(B). 
Go to UODIFETC 

NEWSTAND 

You can immediately boot /unix. 

- Power on (if you want to boot from tape, set the magtape drive to 
ONLINE) 

- hit any key 

the Minitor prompts with 
what ? 


Your input 

Machine Reaction 

Comment 

hk or 


select disk type 

rm or 


(default is HK) 

rl 



/unix 

load /unix 


£ 

start /unix 



However, you should edit /usr/sys/name.c in order to introduce correct 
identifying information, followed by make in the directory /usr/sys. 
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In the directory /usr/local/filesets you will find several files with a suffix of 
'list‘ (e.g. rootlist). These files contain the pathnames of the files distri¬ 
buted with your system. 

In the initial state, as shipped by PCS, the system has only the files from 
rootlist and usrlist copied on its disk(s). If you want to use files from addi¬ 
tional filesets, you have to read them in from your distribuUon media. 

To read in a new set of files, be aware of the following: 

- first, you have to go to / in all cases 

cd / 

- if reading in filesets from tape or streamer cartridge, first rewind the 
tape or the streamer cartridge and then skip the filesets you do not 
need: 


Device 

Commands 

Comment 

tape: 

< /dev/rmtO 
tm fsf n 

cpio -iBmvd < /dev/nrmtO 

rewind tape 

skip n filesets on tape 

read a fileset without rewinding 

streamer: 

< /dev/rstO 
stskip n 

cpio -iSmvd < /dev/nrstO 

rewind streamer cartridge 
skip n filesets on cartridge 
read a fileset without rewinding 


Continue by alternating the skip and the read commands according to your 
needs. After having finished reading in the filesets you need, rewind: 


Device 

Commands 

Comment 

tape: 

< /dev/rmtO 

rewind tape 

streamer: 

< /dev/rstO 

rewind streamer cartridge 


- if reading in from floppies, insert the floppies labeled with the fileset you 
need (any order), and use for each floppy the command: 

cpio -ivmd < /dev/rrx2 

If you wish to remove filesets from your disk(s), we suggest to use the files 
/usr/local /filesets/*list to get complete lists of related files. One way to 
do this is to use the shell command listed bellow: 

sed */~#/d* /usr/local/filesets/xxxlist | sed | \ 

( while read F; do rm SF; done ) 
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MODIFETC 

There are several files, mainly in /etc, which have to reflect your hardware 
configuration, how many terminals you have, what speeds they run on, 
what kinds of terminals are attached and so on. For a description of the 
files, read manual sections 5 and 8. 


You should inspect the following files and modify them if necessary: 


File 

/etc/bcheckrc 
/etc/checklist 
/etc/group 
/etc/inittab 

/etc/issue 
/etc/passwd 
/etc/profile 
/etc/rc 

/usr/lib/crontab 


Reason 

for definition of TZ 

for your disks, used by fsck, look at old /etc/fstab 
add your own groups, do not modify otherwise 
add your terminals and types, look at old /etc/ttys, 
/etc/ttytype 

will be printed before login 

add your own users, do not modify otherwise 

for definition of TZ, look at old /etc/profile 

add your own mount commands, look at old /etc/rc 

used by clock daemon for regular tasks 


You should examine and modify the following files, if you intend to use 
them: 


File 

Reason 

/etc/checkall 

fsck for your disks 

/etc/filesave 

backup shell script 

/etc /gettydefs 

for other speeds 

/etc/motd 

message of the day 

/etc/tapesave 

backup shell script 

/usr/lib/acct/holidays 

for local holiday schedule 


REST0R0LD 

If you saved old files, read them in now. 

ENDOFSETUP j 

Now all files are set up. You can go into multi user mode with mit 2. Make 

sure that you can login at all terminals. 
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1. INTRODUCTION 

This paper describes how to write programs that interface with the UNIX operating system 
in a non-trivial way. This includes programs that use files by name, that use pipes, that invoke 
other commands as they run, or that attempt to catch interrupts and other signals during execu¬ 
tion. 

The document collects material which is scattered throughout several sections of The UNIX 
Programmer's Manual Ill for Version 7 UNIX. There is no attempt to be complete; only gen¬ 
erally useful material is dealt with. It is assumed that you will be programming in C, so you 
must be able to read the language roughly up to the level of The C Programming Language [2]. 
Some of the material in sections 2 through 4 is based on topics covered more carefully there. 
You should also be familiar with UNIX itself at least to the level of UNIX for Beginners (3]. 

2. BASICS 

2.1. Program Arguments 

When a C program is run as a command, the arguments on the command line are made 
available to the function main as an argument count argc and an array argv of pointers to 
character strings that contain the arguments. By convention, argv [0] is the command name 
itself, so argc is always greater than 0. 

The following program illustrates the mechanism: it simply echoes its arguments back to 
the terminal. (This is essentially the echo command.) 

main(argc, argv) /* echo arguments */ 
int argc; 
char *argv(J; 
l 

int 1; 

for (i • 1; i < arge; i++) 

printfargvti], (Karge-1) ? ' ' : '\n'); 

) 

a r g v is a pointer to an array whose individual elements are pointers to arrays of characters; 
each is terminated by \0, so they can be treated as strings. The program starts by printing 
argv Cl) and loops until it has printed them all. 

The argument count and the arguments are parameters to main. If you want to keep them 
around so other routines can get at them, you must copy them to external variables. 

2.2. The “Standard Input** and “Standard Output” 

The simplest input mechanism is to read the “standard input,” which is generally the 
user’s terminal. The function getchar returns the next input character each time it is called. 
A file may be substituted for the terminal by using the < convention: if prog uses geochar. 
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then the command line 
prog <£ils 

causes prog to read file instead of the terminal, prog itself need know nothing about 
where its input is coming from. This is also true if the input comes from another program via 
the pipe mechanism: 

otlierprog I prog 

provides the standard input for prog from the standard output of otherprog. 

getchar returns the value EOF when it encounters the end of file (or an error) on what* 
ever you are reading. The value of EOF is normally defined to be -1, but it is unwise to take 
any advantage of that knowledge. As will become dear shortly, this value is automatically 
defined for you when you compile a program, and need not be of any concern. 

Similarly, putchar (c) puts the character c on the “standard output,” which is also by 
default the terminal. The output can be captured on a file by using >: if prog uses putchar. 

\ 

prog >out£ila 

writes the standard output on outfile instead of the terminal, outfile is crea t ed if it 
doesn’t exist; if it already exists, its previous contents are overwritten. And a pipe can be used: 

p rog I otharprog 

puts the standard output of prog into the standard input of otherprog. 

The function printf, which formats output in various ways, uses the same mechanism as 
putchar does, so calls to printf and putchar may be intermixed, in any order, the output 
will appear in the order of the calls. 

Similarly, the function scanf provides for formatted input conversion; it will read the 
standard, input and break it up into strings, numbers, etc., as desired, scanf uses the same 
mechanism as getchar, so calls to them may also be intermixed. 

Many programs read only one input and. write one output; for such programs I/O with 
getchar. putchar, scanf, and printf maybe entirely adequate, and it is almost always 
enough to get started. This is particularly true if the UNIX pipe facility is used to connect the 
output of one program to the input of the next. For example, the following program strips out 
all ascii control characters from its input (except for newline and tab). 

•include <stdio.h> 

mainO /* ccstrip: strip non-graphic characters •/ 

1 

int e; 

whila ((c - gatcharO) !• EOF) 

if ((c >• ' ' && c < 0177) I I c — '\t' lie — '\n') 
putchar(c); 

•xtt(0); 


The line • 

•include <atdio.h> 

should appear at the beginning of each source file. It causes the C compiler to read a file 
Uusr/inctuddstdio.h) of standard routines and symbols that includes the definidon of EOF. 

If it is necessary to treat muldpie files, you can use cat to collect the files for you: 

cat filel file! ... I ccstrip >output 

and thus avoid learning how to access files from a program. By the way, the call to exit at the 
end is not necessary to make the program work properly, but it assures that any caller of the 





prog ram will see a normal termination status (conventionally 0) from the program when it com* 
pletes. Section 6 discusses status returns in more detail. 

3. THE STANDARD I/O LIBRARY 

The “Standard I/O Library” is a collection of routines intended to provide efficient and 
portable I/O services for most C programs. The standard I/O library is available on each sys¬ 
tem that supports C, so programs that confine their system interactions to its facilities can be 
transported from one system to another essentially without change. 

In this section, we will discuss the basics of the standard I/O library. The appendix con¬ 
tains a more complete description of its capabilities. 

3.1. File Access 

The programs written so far have all read the standard input and written the standard out¬ 
put, which we have assumed are magically pre-defined. The next step is to write a program that 
acf >^ a file that is not already connected to the program. One simple example is wc. which 
counts the lines, words and characters in a set of files. For instance, the command 

we x.e y.c 

prints the number of lines, words and characters in x. c and y. c and the totals. 

The question is how to arrange for the named files to be read — that is, how to connect the 
file system names to the I/O statements which actually read the data. 

The rules are simple. Before it can be read or written a file has to-be opened by the stan¬ 
dard library function fopen. fopen takes an extemai name (like x.e or y.c), does some 
housekeeping and negotiation with the operating system, and returns an internal name which 
must be used in subsequent reads or writes of the file. 

This internal name is actually a pointer, called a file pointer , to a structure which contains 
information about the file, such as the location of a buffer, the current character position in the 
buffer, whether the file is being read or written, and the like. Users don’t need to know the 
details, because part of the standard I/O definitions obtained by including stdio.h is a struc¬ 
ture definition called FILE. The only declaration needed for a file pointer is exemplified by 

FILE *fp, *fopenl); 

This says that f p is a pointer to a FILE, and fopen returns a pointer to a FILE. (FILE is a 
type name, like int, not a structure tag. 

The actual call to fopen in a program is 
fp ■ fopen(name, node); 

The first argument of fopen is the name of the file, as a character string. The second argu¬ 
ment is the mode, also as a character string, which indicates how you intend to use the file. 
The only allowable modes are read ("r"), write ("v"), or append ("a"). 

If a file that you open for writing or appending does not exist, it is created (if possible). 
Opening an existing file for writing causes the old contents to be discarded. Trying to read a 
file that does not exist is an error, and there may be other causes of error as well (like trying to 
read a file when you don’t have permission). If there is any error, fopen will return the null 
pointer value NULL (which is defined as zero in stdio.h). 

The next thing needed is a way to read or write the file once it is open. There are several 
possibilities, of which getc and putc are the simplest, getc returns the next character from 
a file; it needs the file pointer to tell it what file. Thus 

c • gete(fp) 

places in c the next character from the file referred to by fp; it returns EOF when it reaches 
end of file, pure is the inverse of getc; 







- 4 . 


putc(c, fp) 

puts the character c on the file fp and returns c. getc and putc return EOP on error. 

When a program is started, three files are opened automatically, and file pointers are pro¬ 
vided for them. These files are the standard input, the standard output, and the standard error 
output; the corresponding file pointers are called stdin, stdout, and stderr. Normally 
these are aU connected to the terminal, but may be redirected to files or pipes as described in 
Section 2.2. stdin, stdout and stderx are p re-defined in the I/O library as the standard 
input, output and error files; they may be used anywhere an object of type PILE * can be. 
They are constants, however, not variables, so don’t try to assign to them. 

With some of the preliminaries out of the way, we can now write we. The basic design is 
one that has been found convenient for many programs: if there are command-line arguments, 
they are processed in order. If there are no arguments, the standard input is processed. This 
way the program can be used stand-alone or as part of a larger p w v^ 

#include <*tdio.il> 

aela(argc, argv) /♦ we: count lines, words, chars •/ 
int arge; 
char eergvQ ; 

( 

int c, i, in word; 

TXLZ. *tp, efopsaO; 

long linect, wordet, charct; 

long tl ins et - 0, two r det • 0, tcharet • 0; 

i » t; 
fp » stdin; 
do ( 

if (arge > 1 M (fp-fopen(argv£i], -r-)) — NULL) ( 
fprintf(stderr, "vc: can't open argv(i]); 

continue; 

1 

linect » wordet •• charct • inword • 0; 
while ((c - gete(fp)) !■ SOP) ( 
charct**; 
if (e — '\n') 
linect**;- 

if (C — ' ' II C — '\t' lie— '\a') 
inword « 0; 

•lae if (inword — 0) ( 
inword ■ 1; 
wordet**; 

) 

J 

printf("%71d %71d *71d", linect, wordet, charct); 

printf(arge >17- »e\n- : "\n", argv£i]); 

fcloee(fp); 

tlinect linect; 

twordet wordet; 

tcharet *- charct; 

) while (**i < arge); 
if (arge > 2) 

^"*71d *71d *71d total\n", tlinect, twordet, tchaxct ): 

exit(0); 

) 

The function fprintf is identical to printf, save that the first argument is a file pointer that 
specifies the file to be written. 
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The function fclose is the inverse of fopen; it breaks the connection between the file 
pointer and the external name that was established by fopen. freeing the file pointer for 
another file. Since there is a limit on the number of files that a program may have open simul¬ 
taneously it’s a good idea to free things when they are no longer needed. There is also another 
reason to’call fclose on an output file - it flushes the buffer in which pute is collecting out¬ 
put. (fclose is called automatically for each open file when a program terminates normally.) 

3.2. Error Handling — Stderr and Exit 

stderr is assigned to a program in the same way that stdin and stdout are. Output 
.written on stderr appears on the user’s terminal even if the standard output is redirected, we 
writes its diagnostics on stderr instead of stdout so that if one of the files can’t be ac ces sed 
for some reason, the message finds its way to the user’s terminal instead of disappearing down 
a pipeline or into an output file. 

The program actually signals errors in another way, using the function exit to terminate 
program execution. The argument of exit is available to whatever process called it (see Sec¬ 
tion 6), so the success or failure of the program can be tested by another program that uses this 
one as a sub-process. By convention, a return value of 0 signals that all is well; non-zero 
values signal abnormal situations. 

exit itself calls fclose for each open output file, to flush out any buffered output, then 
calls a routine named _exit. The function _exit causes immediate termmauon without any 
buffer flushing; it may be called directly if desired. 

3.3. Miscellaneous I/O Functions 

The standard I/O library provides several other I/O functions besides those we have illus¬ 
trated above. 

Normally output with putc. etc., is buffered (except to stderr); to force it out immedi¬ 
ately, use fflush (fp). 

fscanf is identical to scanf, except that its first argument is a file pointer (as with 
fprintf) that specifies the file from which the input comes; it returns EOF at end of file. 

The functions sscanf and spriatf are identical to fscanf and fprintf, except that 
the first argument names a character string instead of a file pointer. The conversion is done 
from the string for sscanf and into it for sprintf. 

fgets(buf, size, fp) copies the next line from fp, up to and including a newiine, 
into buf; at most size-1 characters are copied; it returns NOLL at end of file, 
fputs (buf, .fp) writes the string in buf onto file fp. 

The function ungetc (c, fp) “pushes back” the character c onto the input stream fp; a 
subsequent call to gebc, f scanf, etc., will encounter c. Only one character of pushback per 
file is permitted. 

4. LOW-LEVEL I/O 

This section describes the bottom level of I/O on the UNIX system. The lowest level of 
I/O in UNIX provides no buffering or any other services; it is in fact a direct entry into the 
operating system. You are entirely on your own, but on the other hand, you have the most 
control over what happens. And since the calls and usage are quite simple, this isn t as bad as 
it sounds. 

4.1. File Descriptors 

In the UNIX operating system, all input and output is done by reading or writing files, 
because all peripheral devices, even the user’s terminal, are files in the file system. This means 
that a single, homogeneous interface handles all communication between a program and peri¬ 
pheral devices. 



• 6 • 


In the most general case, before reading or writing a file, it is neces s a r y to inform the sys¬ 
tem of your intent to do so, a process called “opening” the file. If you are going to write on a 
file, it may also be necessary to create it. The system checks your right to do so (Does the file 
exist? Do you have permission to access it?), and if all is well, returns a small positive integer 
called a file descriptor. Whenever I/O is to be done on the file, the file descriptor is used instead 
of the name to identify the file. (This is roughly analogous to the use of READ(5_) and 
WRITE(6,...) in Fortran.) All information about an open file is maintained by the system; the 
user program refers to the file only by the file descriptor. 

The file pointers discussed in section 3 are similar in spirit to file descriptors, but file 
descriptors are more fundamental. A file pointer is a pointer to a structure that contains, 
among other things, the file descriptor for the file in question. 

Since input and output involving the user’s terminal are so common, special arrangements 
exist to make this convenient. When the command interpreter (the “shell”) runs a program, it 
opens three files, with file descriptors 0, 1, and 2, called the standard input, the standard out¬ 
put, and the standard error output. All of these are normally connected to the terminal, so if a 
program reads file descriptor 0 and writes file descriptors l and 2, it can do terminal I/O 
without wonying about opening the files. 

If I/O is redirected to and from files with < and >, as in 

prog 

the shell changes the default assignments for file descriptors 0 and 1 from the terminal to the 
named files. Similar observations hold if the input or output is associated with a pipe. Nor¬ 
mally file descriptor 2 remains attached to the terminal, so error messages can go there. In all 
the file assignments are changed by the shell, not by the program. The program does not 
need to know where its input comes from nor where its output goes, so.long as it uses file 0 for 
input and 1 and 2 for output 

4.2. Read and Write 

All input and output is done by two functions called read and write. For both, the first 
argument is a file descriptor. The second argument is a buffer in your program where the data 
is to come from or go to. The third argument is the number of bytes to be transferred. The 
calls are 

n.read • readlfd, bu£, a); 

n_vritc*n • vritetfd, buf, a); 

Each call returns a byte count which is the number of bytes actually transferred. On reading, 
the number of bytes returned may be less than the number asked for, because fewer than a 
bytes remained to be read. (When the file is a terminal, read normally reads only up to the 
next newline, which is generally less than what was requested.) A return value of zero bytes 
implies end of file, and -1 indicates an error of some sort. For writing, the returned value is 
the number of bytes actually written; it is generally an error if this isn’t equal to the number 
supposed to be written. 

The number of bytes to be read or written is quite arbitrary. The two most common values 
are 1, which means one character at a time (“unbuffered”), and 512, which corresponds to a 
physical blocksize on many peripheral devices. This latter size will be most efficient, but even 
character at a time I/O is not inordinately expensive. 

Putting these facts together, we can write a simple program to copy its input to its output. 
This program will copy anything to anything, since the input and output can be redirected to 
any file or device. 
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•dafine BUTSIZC 512 /* best size for PDP-11 UNIX */ 

uia() /* copy input to output */ 
l 

buf[BUPSIZC]; 
int n; 

while ((n ■ read(0, buf, BUPSIZC)) > 0) 
write (1, buf, n); 
exit(0); 

) 

If the file size is not a multiple of BUFSIZZ, some read will return a smaller number of bytes 
to be written by write; the next call to read after that will return zero. 

It is instructive to see how read and write can be used to construct higher level routines 
like getchar. putchax, etc. For example, here is a version of getchar which does 
unbuffered input. 

QUtSX 0377 /* for m ak i ng char'* > 0 */ 

getchar() /* unbuffered single character input «/ 

l 

char c; 

return((read(0, ac, 1) > 0) 7c6 QttSX : COP); 

1 

c must be declared char, because read accepts a character pointer. The character being 
returned must be masked with 0377 to ensure that it is positive; otherwise sign extension may 
make it negative. (The constant 0377 is appropriate for the PDP-11 but not nece ss a ri ly for 
other machines.) 

The second version of getchar does input in big chunks, and hands out the characters 
one at a time. 

•define CMASX 0377 /* for making char's > 0 #/ 

•define BUFSXZB 512 

getchar() /• buffered version */ 

l 

static char buf[BUFSIZZ); 

static char *bufp • buf; 

static int n - 0; 

if (n ■» 0) ( /• buffer is empty •/ 

n m read(0 , buf, BUFSIZZ); 
bufp - buf; 

) 

return((—n >— 0) 7 «*bufp ++ a CMASX s COP); 

) 

4.3. Open, Creat, Cose, Unlink 

Other than the default standard input, output and error files, you must explicitly open files 
in order to read or write them. There are two system entry points for this, open and creat 
[sid. 

open is rather like the fopen discussed in the previous section, except that instead of 
returning a file pointer, it returns a file descriptor, which is just an int. 








ino fd; 
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fd ■ open (name, rvmode); 

As with fopan, the name argument is a character string corresponding to the external hie 
name. The mode argument is different, however rwmoda is 0 for read, l for write, and 
2 for read and write access, open returns -1 if any error occurs; otherwise it returns a valid 
hie descriptor. 

It is an error to try to open a file that does not exist The entry point exeat is provided 
to create new files, or to re-write old ones. 

fd ■ craaP(naaa, paoda); 

returns a file descriptor if it was able to create the file called name, and -1 if not If the file 
already exists, exeat will truncate it to zero length; it is not an error to exeat a file that 
already exists. 

If the file is brand new, exeat creates it with the protection mode specified by the pxnode 
argument In the UNIX file system, there are nine bits of protection information associated 
with a file, controlling • read, write and execute permission for the owner of the file, for the 
owner’s group, and for all others. Thus a three-digit octal number is most convenient for 
specifying the permissions. For example, 0755 specifies read, write and execute permission for 
the owner, and read and execute permission for the group and everyone else. 

To illustrate, here, is a simplified version of the UNIX utility cp, a program which copies one 
file to another. (The main simplification is that our version copies only one file, and does not 
permit the second argument to be a directory.) 

Idafina NULL 0 
Idafin* BUTS122 SI 2 

tdafiaa PMOQX 0644 /• RW for ownar, R for gro up , othara */ 

main (arge, argv) /• cp: cop y £1 to f2 •/ 
tap arge; 
char *argv(]; 

( 

imP fl, £2, n; , 

char buf[BUTS122]; 

If (arge l» 3) 

error("Uaaga: cp from Po", ROLL); 
if ((fl » open(argv(1], 0)) ••-1) 

e r ror("cp: can'p open *a", argv(ll); 
if ((£2 • craa£(argv(2], PMCOB)) — -1) 

error("cp: can'P craaPa %•", argv[2]); 

vhila ((a • readtfl, buf, BUTS222)) > 0) 
if (vriPa(£2, buf, a) !• a) 

error ("cp:. vriPe e r ror", MOLL); 

eziP(b); 

) 

% 

error (si, a2) /« primp error meaaaga and die •/ 

char *a1, *a2; 

( 

prinpf(a1 ( *2); 
priap£("\a"); 
exit (1); 

] 
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As we said earlier, there is a limit (typically 15-25) on the number of files which a program 
may have open simultaneously. Accordingly, any program which intends to process many files 
must be prepared to re-use file descriptors. The routine close breaks the connection between 
a file descriptor and an open file, and frees the file descriptor for use with some other file. Ter¬ 
mination of a program via exit or return from the main program closes all open files. 

The function unlink (filename) removes the file filename from the file system. 

4.4. Random Access — Seek and Lseek 

File I/O is normally sequential: each read or write takes place at a position in the file 
right after the previous one. When necessary, however, a file can be read or written in any 
arbitrary order. The system call lseek provides a way to move around in a file without actu¬ 
ally reading or writing: 

lseek(fd, offset, origin); 

forces the current position in the file whose descriptor is fd to move to position offset, 
which is taken relative to the location specified by origin. Subsequent reading or writing will 
begin at that position, offset is a long; fd and origin are int’s. origin can be 0, 1, 
or 2 to specify that offset is to be measured from the beginning, from the current position, 
or from the end of the file respectively. For example, to append to a file, seek to the end 
before writing: 

lseek (fd, OX., 3); 

To get back to the beginning (“rewind”), 
lseek (fd, OX., 0); 

Notice the 0L argument; it could also be written as (long) 0. 

With lseek. it is possible to treat files more or less like large arrays, at the price of slower 
access. For example, the following simple function reads any number of bytes from any arbi¬ 
trary place in a file. 

get(fd, pos, buf, n) /* read n bytes from position pos */ 
int fd, n; 
long pos; 

'char *buf; 
l 

lse«k(fd, pos, 0); /* gat to pos •/ 

return(read(fd, buf, n)); 

» 

In pre-version 7 UNIX, the basic entry point to the I/O system is called seek seek is 
identical to lseek except that its offset argument is an int rather than a long. Accord¬ 
ingly, since PDP-11 integers have only 16 bits, the offset specified for seek is limited to 
65,535; for this reason, origin values of 3, 4, 5 cause seek to multiply the given offset by 
512 (the number of bytes in one physical block) and then interpret origin as if it were 0, 1, 
or 2 respectively. Thus to get to an arbitrary place in a large file requires two seeks, first one 
which selects the block, then one which has origin equal to 1 and moves to the desired byte 
within the block. 

4.5. Error Processing 

The routines discussed in this section, and in fact all the routines which are direct entries 
into the system can incur errors. Usually they indicate an error by returning a value of — 1. 
Sometimes it is nice to know what sort of error occurred; for this purpose all these routines, 
when appropriate, leave an error number in the external cell ermo. The meanings of the 
various error numbers are listed in the introduction to Section II of the UNIX Programmer's 
Manual, so your program can, for example, determine if an attempt to open a file failed 
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because it did not exist or because the user lacked permission to read it. Perhaps more com* 
moniy, you may want to print out the reason for failure. The routine perxor will print a mes¬ 
sage associated with the value of errno; more generally, syi.ermo is an array of character 
strings which can be indexed by errno and printed by your program. 

S. PROCESSES 

It is often easier to use a program written by someone else than to invent one’s own. This 
section describes how to execute a program from within another. 

5.1. The “System” Function 

The easiest way to execute a program from another is to use the standard library routine 
system, system takes one argument, a command string exactly as typed at the terminal 
(except for the newline at the end) and executes it. For instance, to time-stamp the output of 
a program, 

a«in() 

t 

system ("date") ; 

/* zest of processing •/ 

) 

If the command string has to be built from pieces, the in-memory formatting capabilities of 
sprint* may be useful. 

Remember than gate and putc normally buffer their input; terminal I/O will not be prop¬ 
erly synchronized unless this buffering is defeated. For output, use ffluah; for input, see 
setlsuf in the appendix. 

5.2. Low-Level Pro ce ss Creation — Exed and Execv 

If you’re not using the standard library, or if you need finer control over what happens, you 
will have to construct calls to other programs using the more primitive routines that the stan¬ 
dard library’s system routine is based on. 

The most basic operation is to execute another program without returning , by using the rou¬ 
tine execl. To print the date as the last action of a running program, use 

execl("/Pin/date", "date", NULL); 

The first argument to execl is the /fie name of the command; you have to know where it is 
found in the file system. The second argument is conventionally the program name (that is, 
the last component of the file name), but this is seldom used except as a place-holder. If the 
command takes arguments, they are strung out after this; the end of the list is marked by a 
NULL argument. 

The execl call overlays the existing program with the new one, runs that, then exits. 
There is no return to the original program. 

More realistically, a program might fall into two or more phases that communicate only 
through temporary files. Here it is natural to make the second pass simply an execl call from 
the first. 

The one exception to the rule that the original program never gets control back occurs 
when there is an error, for example if the file can’t be found or is not executable. If you don't 
know where date is located, say 

execl("/Pin/date", "data", NULL); 
execl("/usr/Pin/data", "date", NULL); 
fprintf(stderr, "Sooeone stole 'date'Nn"); 

A variant of execl called execv is useful when you don’t know in advance how many 
arguments there are going to be. The call is 
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execv(filename, argp); 

where argp is an array of pointers to the arguments; the last pointer in the array must be 
NOLL so execv can tell where the list ends. As with execl, filename is the file in which 
the program is found, and argp CO] is the name of the program. (This arrangement is identi¬ 
cal to the argv array for program arguments.) 

Neither of these routines provides the niceties of normal command execution. There is no 
automatic search of multiple directories - you have to know precisely where the command is 
located. Nor do you get the expansion of metacharacters like <,>,*,?, and C3 in the argu¬ 
ment list. If you want these, use exeel to invoke the shell sh, which then does all the work. 
Construct a string commend line that contains the complete command as it would have been 
typed at the terminal, then say 

execl("/bia/sk", "sh", "-c", comaadline, NULL); 

The shell is assumed to be at a fixed place, /toin/sh. Its argument -c says to treat the next 
argument as a whole command Une, so it does just what you want. The only problem is in con¬ 
structing the right information in co mman dllne. 

5.3. Control of Processes — Fork and Wait 

So far what we’ve talked about isn’t really all that useful by itself. Now we will show how 
to regain control after running a program with exed or execv. Since these routines simply 
overlay the new program on the old one, to save the old one requires that^it first be split into 
two copies; one of these can be’overlaid, while the other waits for the new, overlaying program 
to finish. The splitting is done by a routine called f ork: 

proc_id • fork(); 

splits the program into two copies, both of which continue to run. The only difference between 
the two is the value of proc.id, the “process id.” In one of these pro ce sses (the “child ), 
proc.id is zero. In the other (the “parent”), proc.id is non-zero; it is the process number 
of the"cfaild. Thus the basic way to call, and return from, another program is 

if (forkO 0) 

exeel("/bin/sh", "*h", "-c", cad, NULL); /* in child */ 

And in fact, except for handling errors, this is sufficient. The fork makes two copies of the 
program. In the child, the value returned by fork is zero, so it calls execl which does the 
command and then dies. In the parent, fork returns non-zero so it skips the execl. (If 
there is any error, fork returns -1). 

More often, the parent wants to wait for the child to terminate before continuing itself. 
This can be done with the function wait: 

int statue; 

if (forkO — 0) 
execl(...); 
wait(tstatus); 

This still doesn’t handle any abnormal conditions, such as a failure of the execl or fork, or 
the possibility that there might be more than one child running simultaneously. (The wait 
returns the process id of the terminated child, if you want to check it against the value returned 
by fork.) Finally, this fragment doesn’t deal with any funny behavior on the part of the child 
(which is reported in status). Still, these three lines are the heart of the standard library’s 
system routine, which we’ll show in a moment. 

The status returned by wait encodes in its low-order eight bits the system’s idea of the 
child’s termination status; it is 0 for normal termination and non-zero to indicate various kinds 
of problems. The next higher eight bits are taken from the argument of the call to exit which 
caused a normal termination of the child process. It is good coding practice for all programs to 
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retum meaningful status. 

When a program is called by the shell, the three file descriptors 0, l, and 2 are set up point¬ 
ing at the right files, and all other possible file descriptors are available for use. When this pro¬ 
gram calls another one, correct etiquette suggests making sure the same conditions hold. Nei¬ 
ther fork nor the exec calls affects open files in any way. If the parent is buffering output 
that must come out before output from the child, the parent must flush its buffers before the 
execl. Conversely, .if a caller buffers an input stream, the called program will lose any infor¬ 
mation that has been read by the caller. 

5.4. Pipes 

A pipe is an I/O channel intended for use between two cooperating processes: one process 
writes into the pipe, while the other reads. The system looks after buffering the data and syn¬ 
chronizing the two processes. Most pipes are created by the shell, as in 

lx I pr 

which connects the standard output of Is to the standard input of pr. Sometimes, however, it 
is most convenient for a proce ss to set up its own plumbing: in this section, we will illustrate 
how the pipe connection is established and used. 

The system gall pipe creates a pipe; Since a pipe is used for both reading and writing, two 
file descriptors are returned; the actual usage is like this: 

ine. id [21; 

seat - pipe(fd); 

if (star — -1) 

/*- thmv wax aa arzor ... */ 

fd is an array of two file descriptors, where fd[0] is the read side of the pipe and fdtl 1 is 
for writing. These may be used in read, write and close calls just tike any other file 
descriptors. 

If a process reads a pipe which is empty, it will wait until data arrives; if a process writes 
into a pipe which is too full, it will wait until the pipe empties somewhat. If the write side of 
the pipe is closed, a subsequent read will encounter end of file. 

To illustrate the use of pipes in a realistic setting, let us write a function called 
popenicad, mode), which creates a process cad Oust as system does), and returns a file 
descriptor that will either read or write that process, according to mode. That is, the call 

four • popenCpr", WRITE); 

creates a process that executes the pr command; subsequent write calls using the file descrip¬ 
tor f out will send their data to that process through the pipe. 

popen first creates the the pipe with a pipe system call; it then forks to create two 
copies of itself. The child decides whether it is supposed to read or write, closes the other side 
of the pipe, then calls the shell (via execl) to run the desired process. The parent likewise 
closes the end of the pipe it does not use. These closes are necessary to make end-of-file tests 
work properly. For example, if a child that intends to read fails to close the write end of the 
pipe, it will never see the end of the pipe file, just because there is one writer potentially active. 
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•include <stdio.h> 

•define READ 0 
•define WRITS 1 

•define tst(a, b) (node — READ ? (b) : (a)} 
static 1 int popen_pidj 

pop«n(cad, node) 
char *cad; 
int node; 

( 

int p [21; 

if (pipa(p) < 0) 

return(NULL); 

if ((popen_pid » forkO) — 0) { 

close(tat(p[WRITE1, p[READ])); 

close(tst(0, 1)); 

dup(tat(p[READ ], p[WRITE])); 

Close(tst(p[READ], p(WRZTE])); 
exeel("/bin/ah", "sh", "-c", cad, 0); 

.exit(1) ; /• disaster has occurred if we get here */ 

1 

if (popen_pid -1) 
return(MULL); 

close(tat(p[READ], ptWRlTE])); 

return(tat(p[WRITE], pfREAD])); 

) 

The sequence of closes in the child is a bit tricky. Suppose that the task is to create a child 
process that will read data from the parent. Then the first close doses the write side of the 
pipe, leaving the read side open. The lines 

close(tst(0, D); 

dup(tat(p[REAS], p[WRITE])); 

are the conventional way to associate the pipe descriptor with the standard input of the child. 
The close closes file descriptor 0, that is. the standard input, dup is a system call that returns 
a duplicate of an already open file descriptor. File descriptors are assigned in increasing order 
and the first available one is returned, so the effect of the dup is to copy the file descriptor for 
the pipe (read side) to file descriptor 0; thus the read side of the pipe becomes the standard 
input. (Yes, this is a bit tricky, but it’s a standard idiom.) Finally, the old read side of the pipe 
is dosed. 

A similar sequence of operations takes place when the child process is supposed to write 
from the parent instead of reading. You may find it a useful exercise to step through that case. 

The job is not quite done, for we still need a function pclose to close the pipe created by 
popen. The main reason for using a separate function rather than close is that it is desirable 
to wait-for the termination of the child process. First, the return value from pclose indicates 
whether the process succeeded. Equally important when a process creates several children is 
that only a bounded number of unwaited-for children can exist, even if some of them have ter¬ 
minated: performing the wait lays the child to rest Thus: 






- 14 - 


•include <signal.h> 

pclosa(fd) /* closa pipa fd */ 

int fd; 

r^litu i, (*baeat)(), (•!*«*«)(), (*q»tae) 0; 

iat status; 

axtsrn int pcp«n_pid; 

• ' qloaa(fd); 

imt - signal (SIGIST, SXG_IGM); 
qsut ■ signal (SI&2U1T, SXG.XQt); 
hatit - signal (SIGHUP, SXG.IGH) ? 

vhila ((r - wait Ustatus)) !- poparjjid « r !■ -1); 
if (r — -1) 

statu* » -1; 
signal (SIGXHT, is tat); 
signal(SXGgCXT, qstat); 

signal(SXCHUP, hatat); < 

rstura( status); 

J 

The calls to signal make sure that no interrupts, etc, interfere with the waiting process; this 
is the topic of the next section. 

The routine as written has the limitation that only one pipe may be open at once, because 
of the single shared variable popen_pidU it really should be an array indexed by file descrip¬ 
tor. A popen function, with slightly different arguments and return value is available as part 
of the standard I/O library discussed below. As currently written, it shares the same limitation. 

6. SIGNALS — INTERRUPTS AND ALL THAT 

This section is concerned with how to deal gracefully with signals from the outside world 
(like interrupts), and with program faults. Since there’s nothing very useful that can be done 
from within C about program faults, which arise mainly from illegal memory references or from 
execution of peculiar instructions, we’ll discuss only the outside-world signals: interrupt, which 
is sent when the DEL character is typed; quit, generated by the FS character, hangup, caused by 
hanging up the phone; and terminate , generated by the kilt command. When one of these 
events occurs, the signal is sent to ait processes which were started from the corresponding ter¬ 
minal; unless other arrangements have been m ad e, the signal terminates the process. In the 
quit case, a core image file is written for debugging purposes. 

The routine which alters the default action is called signal. It has two arguments: the 
first specifies the signal, and the second specifies how to treat it The first argument is just a 
number code, but the second is the address is either a function, or a somewhat strange code 
that requests that the signal either be ignored, or that it be given the default action. The 
include file signal.h gives names for the various arguments, and should always be included 
when signals are used. Thus 

iinclud* signal .h> 

• * • 

signal (SIGXST, SXG.XQO ; 

causes interrupts to be ignored, while 

signal (SXGXHT, SIG.OIX.) ; 

restores the default action of process termination. In all cases, signal returns the previous 
value of the signal The second argument to signal may instead be the. name of a function 
(which has to be declared explicitly if the compiler hasn’t seen it already). In this case, the 
named routine will be called when the signal occurs. Most commonly this facility is used to 
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allow the program to clean up unfinished business before terminating, for example to delete a 
temporary file: 

•include <signal.h> 

mainO 

1 

1st onintr(); 

if (signal(SZGZNT, SZG.ZGH) I- SZG.ZGN) 
signal (SIGXNT, onintr); 

/* Process ... •/ 

«x±t(0); 

) 

onintr() 

( 

unlink (tesrpfile) ; 

•adtd); 

» 

Why the test and the double call to signal? Recall that signals like interrupt are sent to 
all proces se s started from a particular terminal Accordingly, when a program is to be run non* 
interactively (started by &), the shell turns off interrupts for it so it won’t be stopped by inter* 
rupts intended for foreground processes. If this program began by announcing that all inter¬ 
rupts were to be sent to the onintr routine regardless, that would undo the shell’s effort to 
protect it when run in the background. 

The solution, shown above, is to test the state of interrupt handling, and to continue to 
ignore interrupts if they are already being ignored. The code as written depends on the fact 
that signal returns the previous state of a particular signal. If signals were already being 
ignored, the process should continue to ignore them; otherwise, they should be caught. 

A more sophisticated program may wish to intercept an interrupt and interpret it as a 
request to stop what it is doing and return to its own command-processing loop. Think of a 
text editor: interrupting a long printout should not cause it to terminate and lose the work 
already done. The outline of the code for this case is probably best written like this: 

tinclod* <signal.h> • 

•include <setjnp.h> 
jnp_buf sjbuf; 

mainO 

1 

ine («istat)(), onintr(); 

istat • signal (SZGZNT, SIG_XGN); /• sav* original status */ 

setjnp(sjbuf); /* save current stack position •/ 
if (istat I- SZG.ZOt) 

signal(SZGZNT, onintr); 

/* main processing loop */ 


). 
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onintr() 

I 

print*("NnlnterruptNn"); 

longjmp(sjbuf); /* return to saved state •/ 

» 

The include file setjmp.h declares the type jmp_buf an’object in which the sute can be 
saved, s jbuf is such an object; it is an array of some sort. The aetjmp routine then saves 
the state of things. When an interrupt occurs, a call is forced to the onintr routine, which 
can print a message, set flags, or whatever, long jap takes as argument an object stored into 
by set jap, and restores control- to the location after the call to setjap, so control (and the 
stack level) will pop back to the place in the main routine where the signal is set up and the 
main loop entered. Notice, by the way, that the signal gets set again after an interrupt occurs. 
This is necessary; most signals are automatically reset to their default action when they occur. 

Some programs that want to detect signals simply can’t be stopped at an arbitrary point, for 
example in the middle of updating a linked list. If the routine called on occurrence of a signal 
sets a flag and then returns instead of calling exit or long jap, execution will continue at the 
exact point it was interrupted. The interrupt flag can then be tested later. 

There is one difficulty associated with this approach. Suppose the program is reading the 
terminal when the interrupt is sent The specified routine is duly called; it sets its flag and 
returns. If it were really true, as we said above, that “execution resumes at the exact point it 
was interrupted,” the program would continue reading the terminal until the user typed another 
line. This behavior might well be confusing, since the user might not know that the program is 
reading; he presumably would prefer to have the signal take effect instantly. The method 
chosen to resolve this difficulty is to terminate the terminal read when execution resumes after 
the signal, returning an error code which indicates what happened. 

Thus programs which catch and resume execution after signals should be pr e pa r ed for 
“errors” which are caused by interrupted system calls. (The ones to watch out for are reads 
from a terminal, wain, and pause.) A program whose onintr program just sets intf lag, 
resets the interrupt signal, and returns, should usually include code like the following when it 
reads the standard input: 

if (getehaxO — SO?) 
if (intflag) 

/* EOF caused by interrupt */ 

else 

/* true end-of-file */ 

A Anal subtlety to keep in mind becomes important when signal-catching is combined with 
execution of other programs. Suppose a program catches interrupts, and also includes a method 
(like “!” in the editor) whereby other programs can be executed. Then the code should look 
something like this: 

if (forJct) — 0) 

exacl (...); 

signal (SIGZ3TT, SIC.IGS); /• ignore interrupts */ 
vaitUatatus); /* until the child is done •/ 
signal(SZCZhT, onintr); /• restore interrupts •/ 

Why is this? Again, it’s not obvious but not really difficult. Suppose the program you call 
catches its own interrupts. If you interrupt the subprogram, it will get the signal and return to 
its main loop, and probably read your terminal. But the calling program will also pop out of its 
wait for the subprogram and read your terminal. Having two processes reading your terminal is 
very unfortunate, since the system figuratively flips a coin to decide who should get each line of 
input. A simple way out is to have the parent program ignore interrupts until the child is done. 
This reasoning is reflected in the standard I/O library function system: 
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tinclud* <signal.h> 

syscem(s) /• run command serin? s •/ 
char *s; 
l 

int sea cos, pid, w; 

ragiatar int (*iaear)(), («qstat)(); 

if ((pid - for* (}) •« 0) l 

axael("/toin/sh", "sh", "-c", s,.0); 

.exit(127); 

) 

iseat - signal (SIGUTT, SIG.IGN) ; 

qstat - signal(SIGQUIT, SIG.IGN); 

whila ((w • wait(Aseaeus)) I- pid && w t« -1) 

a 

if (w — -1) 

status - -1; 
signal(SIGINT, istat); 
signal(SIGQUIT, qstat); 
ratnrn(status); 

1 

As an aside on declarations, the function signal obviously has a rather strange second 
argument. It is in fact a pointer to a function delivering an integer, and this is also the type of 
the signal routine itself. The two values SIG.IGN and SZG.OFL have the right type, but are 
chosen so they coincide with no possible actual functions. For the enthusiast, here is how they 
are defined for the PDP>11; the definitions should be sufficiently ugly and nonportable to 
encourage use of the include file. 

•define SIG.DFL (int <*)0)0 
•define SIG.IGN (lac (*)())! 
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Appendix — The Standard I/O Library 

D. M. R itchie 

Bell Laboratories 
Murray Hill, New Jersey 07974 

The standard I/O library was designed with the following goals in mind. 

1. It must be as efficient as possible, both in time and in space, so that there will be no hesita¬ 
tion in using it no matter how critical the application. 

2. It must, be simple to use, and also free of the magic numbers and mysterious calls whose 
use mars the understandability and portability of many programs using older packages. 

3. The interface provided should be applicable on all machines, whether or not the programs 
which implement it are directly portable to other systems, or to machines other than the 
PDP-11 running a version of UNIX. 

1. General Usage 

Each program using the library must have the line 
tinclude <atdio.h> 

which defines certain macros and variables. The routines are in the normal C library, so no 
special library argument is needed for loading. All names in the include file intended only for 
internal use begin with an underscore _ to reduce the possibility of collision with a user name. 
The names intended to be visible outside the package are 

stdin The name of the standard input file 
s-tdeut The name of the standard output file 
stderr The name of the standard error file 

EOF is actually — 1, and is the value returned by the read routines on end-of-file or error. 

HULL is a notation for the null pointer, returned by pointer-valued functions to indicate an 

error 

?ILZ expands to s tru c t .iota and is a useful shorthand when declaring pointers to 
streams. 

BUFSX2 is a number (viz. 512) of the size suitable for an I/O buffer supplied by the user. 

See sethuf, below. 

gate, getchar, putc, putchar, faof, ferror, fileno 

are defined as macros. Their actions are described below; they are mentioned here 
to point out that it is not possible to redeclare them and that they are not actually 
functions; thus, for example, they may not have breakpoints set on them. 

The routines in this package offer the convenience of automatic buffer allocation and out¬ 
put flushing where appropriate. The names stdin. stdout, and stderr are in effect con¬ 
stants and may not be assigned to. 

2. Calls 

FILE *fopen{filename, type) char ^filename, *type; 

opens the file and, if needed, allocates a buffer for it. filename is a character string 
specifying the name, type is a character string (not a single character). It may be "r", 
"v'\ or "a" to indicate intent to read, write, or append The value returned is a file 
pointer. If it is HULL the attempt to open failed 

FILE *freopen(filename, type, iop-tr) char vfilename; *type; FILE *ioptr 
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The stream named by ioptx is dosed, if necessary, and then reopened as if by f open. If 
the attempt to open fails. HULL is returned, otherwise ioptx. which will now refer to the 
new file. Often the reopened stream is stdin or stdout. 

int getc(ioptx) FILS *ioptx; 

returns the next character from the stream named by ioptx. which is a pointer to a file 
such as returned by f open, or the name stdin. The integer EOF is returned on end-of- 
file or when an error occurs. The null character \0 is a legal character. 

int fgete(ioptx) FILE *ioptx? 

acts like getc but is a genuine function, not a macro; so it can be pointed to, passed as an 
argument, etc. 

putc(c , ioptx) FILE *ioptx; 

putc writes the character c on the output stream named by ioptx. which is a value 
returned from £ open or perhaps stdout or stdexx. The character is returned as value, 
but EOF is returned on error. 

fputc(c, ioptx) FILE *ioptx; 

acts like putc but is a genuine function, not a macro. 

fclose(ioptx) FILS *ioptx; 

The file corresponding to ioptx is closed after any buffers are emptied. A buffer allocated 
by the I/O system is freed. £close is automatic on normal termination of the program. 

fflush(ioptx) FILE *ioptx; 

Any buffered information on the (output) stream named by ioptx is written out. Output 
files are normally buffered if and only if they are not directed to the terminal; however, 
stdexx always starts off unbuffered and remains so unless sethuf is used, or unless it is 
reopened. 

exit (exxcode); 

terminates the process and returns its argument as status to the parent This is a special 
version of the routine which calls f f lush for each output file. To terminate without flush* 
ing, use .exit. 

feof(ioptx) FILE *ioptx; 

returns non-zero when end-of-file has occurred on the specified input stream, 
fexxox(ioptx) FILE *ioptx; 

returns non-zero when an error has occurred while reading or writing the named stream. 
The error indication lasts until the file has been dosed. 

getchax(); 

is identical to getc (stdin). 
putchax(c); 

is identical to putc(c, stdout). 

chax *fgets(s, n, ioptx) chax *s; FILE *ioptx; 

reads up to n-1 characters from the stream ioptx into the character pointer s. The read 
terminates with a newline character. The newline character is placed in the buffer followed 
by a null character, fgets returns the first argument, or NULL if error or end-of-file 
occurred. 

fputs(s, ioptx) chax *s; FILE *ioptx; 

writes the null-terminated string (character array) s on the stream ioptx. No newline is 
appended. No value is returned. 

ungetc(c, ioptx) FILE *ioptx; 


f 
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The argument character c is pushed back on the input stream named by ioptr. Only one 
character may be pushed back. 

printf(format, al, ...) char •format; 

fprintf(ioptr, format, al, ...) FILS *ioptr; char *format; 
sprintf(s, format, al, ...)char *a, •format; 

printf writes on the standard output, fprintf writes on the named output stream, 
sprintf puts characters in the character array (string) named by s. The specifications are 
as described in section printf (3) of the UNIX Programmer’s Manual 

scanf(format, al, ...) char *format; 

fscanf(ioptr, format, al, ...) FXLZ *ioptr; char *format; 
sscanfCs, format, al, ...) char *a, *format; 

scanf reads from the standard input fscanf reads from the named input stream, 
sscanf reads from the character string supplied as s. scanf reads characters, interprets 
them according to a format and stores the results in its arguments. Each routine expects 
as arguments a control string format, and a set of arguments, each of which must be a 
pointer, indicating where the converted input should be stored. 

scanf returns as its value the number of successfully matched and assigned input items. 
This can be used to decide how many input items were found. On end of file, 207 is 
returned; note that this is different from 0, which means that the next input character does 
not match what was called for in the control string. 

fread(ptr, sizeof(*ptr), nit em a, ioptr) FXLZ *ioptr; 
reads nitema of data beginning at ptr from file ioptr. No advance notification that binary 
I/O is being done is required; when, for portability reasons, it becomes required, it will be done 
by adding an additional character to the mode-string on the f open calL 

f writs(ptr, aizeof(*ptr), nitema, ioptr) FXLZ *ioptr; 

Like freed, but in the other direction. 

rewind(ioptr) FXLZ *ioptr; 

rewinds the stream named by ioptr. It is not very useful except on input, since a rewound 
output file is still open only for output 

system(string) char *string; 

The string is executed by the shell as if typed at the terminal. 

getv(ioptr) FXLZ *ioptr; 

returns the next word from the input stream named by ioptr. ZOF is returned on end-of-file 
or error, but since this a perfectly good integer f eof and ferror should be used. A “word” 
is 16 bits on the PDP-11. 

putw(v, ioptr) FXLZ *ioptr.; 

writes the integer w on the named output stream. 

setbuf(ioptr, buf) FXLZ *ioptr; char *buf; 

sethuf may be used after a stream has been opened but before I/O has started. If buf is 
NULL, the stream will be unbuffered. Otherwise the buffer supplied will be used. It must be a 
character array of sufficient size: • 

char buf[BU7SX21; 

fileno (ioptr) FXLZ *ioptr;. 

returns the integer file descriptor associated with the file. 

fseelc(ioptr, offset, ptmame) FXLZ *ioptr; long offset; 

The location of the next byte in the stream named by ioptr is adjusted, offset is a long 
integer. If ptmame is 0, the offset is measured from the beginning of the file; if ptmame is 
1. the offset is measured from the current read or write pointer, if ptmame is 2, the offset is 
measured from the end of the file. The routine accounts properly for any buffering. (When 
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this routine is used on non-UNIX systems, the offset must be a value returned from ftell and 
the ptmame must be 0). 

long ftell(ioptr) PILE *ioptr? 

The byte offset, measured from the beginning of the file, associated with the named stream is 
returned. Any buffering is properly accounted for. (On non-UNIX systems the value of this 
call is useful only for handing to fseelc, so as to position the file to the same place it was when 
ftell was called.) 

getpw(uid, buf) char *buf; 

The password file is searched for the given integer user ID. If an appropriate line is found, it is 
copied into the character array buf, and 0 is returned. If no line is found corresponding to the 
user ID then 1 is returned. 

char *malloc (num); 

allocates num bytes. The pointer returned is sufficiently well aligned to be usable for any pur¬ 
pose. HULL is returned if no space is available. 

char *calloc(num, size); 

allocates space for num items each of size size. The space is guaranteed to be set to 0 and the 
pointer is sufficiently well aligned to be usable for any purpose. HULL is returned if no space is 
available. * 

cfree(pur) char *ptr; 

Space is returned to the pool used by calloc. Disorder can be expected if the pointer was not 
obtained from calloc. 

The following are macros whose definitions may be obtained by including <ctype.h>. 
isalpha (c) returns non-zero if the argument is alphabetic, 
isupper (c) returns non-zero if the argument is upper-case alphabetic 
islover (c) returns non-zero if the argument is lower-case alphabetic 
isdigit (c) returns non-zero if the argument is a digit 

iaspace (c) returns non-zero if the argument is a spacing character tab, newline, carriage 
return, vertical tab, form feed, space. 

ispunct(c) returns non-zero if the argument is any punctuation character, i.e., not a space, 
letter, digit or control character. 

izalnum (c) returns non-zero if the argument is a letter or a digit 

isprint (c) returns non-zero if the argument is printable — a letter, digit, or punctuation 
character. 

iscntrl (c) returns non-zero if the argument is a control character, 
isascii (c) returns non-zero if the argument is an ascii character, i.e., less than octal 0200. 
toupper(c) returns the upper-case character corresponding to the lower-case letter c. 
tolover (c) returns the lower-case character corresponding to the upper-case letter c. 
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1. NOTATION 

The notation used in this document is a modified BNF similar to that used in 
the MULTICS PL/I Language Manual. The operators of the BNF in order of 
decreasing precedence are: 

x ... Repetition: Denotes one or more occurrences of 

x. 

xy Juxtaposition: Denotes an occurrence of x 

followed by an occurrence of y 
x|y Alternation: Denotes an occurrence of x or y 

but not both. 


Brackets and braces define the order of expression interpretation. The 
subexpression enclosed in brackets is optional. That is, 

[x] denotes zero or one occurrence of x. 

jxtyjz _ denotes an x or a y, followed by a z. _ 


Brackets or braces which appear in a68 syntax will be boldfaced, to distin¬ 
guish them from the meta- brackets and braces. 


2. SOURCE PROGRAM FORMAT 

An a68 program consists of a series of statements, each of which occupies 
exactly one line, i.e., a sequence of characters followed by the newline char¬ 
acter. Form feed, ascii ~L, also serves as a line terminator. Neither multiple 
statements on a single line nor continuation lines are allowed. 

The format of an a68 assembly language statement is: 

[LabelField :] op-code [OperandField] [|comment] 

There are three exceptions to this rule: 

1. Blank lines are permitted. 

2. A statement may contain only a LabelField. The label defined in this 
field has the same value as if it were defined in the LabelField of the 
next statement in the program For example, the two statements 

sea: 

movw dl,d2 

are equivalent to the single statement — 

sea: movw dl,d2 

3. A line may consist of only the comment field. For example, the two state¬ 
ments below are allowed: 
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| This is a comment field, 
j So is this 


In general, blanks or tabs are allowed anywhere in a statement. For example, 
multiple blanks are allowed in the Cperandfleld to separate symbols from 
operators. Blanks are meaningful only when they occur in a character string 
(e.g. as the operand of an .ascii pseudo-op). At least one blank or tab must 
appear between the op-code and the Cperandfleld of a statement. 


2.1. Label Fields 

A label is a user-defined symbol which is assigned the value of the current 
location counter and entered into the assembler's symbol table. The value 
of the label may be either absolute or relocatable; in the latter case, the 
absolute value of the symbol is assigned when the program is linked via Id. 

A label is a symbolic means of referring to a specific location within a pro¬ 
gram. If present, a label always occurs first in a statement and must be 
terminated by a colon. The collection of label definitions in a statement is 
called the Labelfleld. 

The format of a Labelfleld is: 
symbol; [symbol:] ... 


Examples: 

start: 

sea: bar: | Multiple symbols 

73: | A local symbol, defined below 


2.2. Op-code Fields 

The Cpcodefield of an assembly language statement identifies the state¬ 
ment as either a machine instruction, or an assembler directive. One or 
more blanks (or tabs) must separate the Cpcodefield from the Operand- 
Field in a statement. No blanks are necessary between LabelFields and 
OpcodeFields, but they are recommended to improve readability of the 
program. 

A machine instruction is indicated by an instruction mnemonic. The 
assembly language statement is intended to produce a single executable 
machine instruction. The operation of each instruction is described in the 
manufacturer’s user manual. Some conventions used in a68 for instruc¬ 
tion mnemonics are described in section 4 and a complete list of the 
instructions is presented in the appendix. 
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An assembler directive, or pseudo-op, performs some function during the 
assembly process. It does not produce any executable code, but it may 
assign space in a program for data. 


2.3. Operand Fields 

A distinction is made between OperandFLeld and operand in a68. Several 
machine instructions and assembler directives require two or more argu¬ 
ments, and each of these is referred to as an operand. In general, an 
Operandfleld consists of zero or more operands, and in all cases, 
operands are separated by a comma. In other words, the format for an 
OperandFleld is: 

[operand [, operand] ...] 

The format of the Operandfleld for machine instruction statements is the 
same for all instructions, and is described in section 4. The format of the 
Operandfleld for assembler directives depends on the directive itself, and 
is included in the directive’s description in section 5 of this manual. 


2.4. Comment Field 

The comment character in a68 is the vertical bar, (D, not the semicolon, 
(;). Use of the semicolon as a comment character will result in an "Invalid 
Operator" error. 

The comment field consists of all characters on a source line following and 
including the comment character. These characters are ignored by the 
assembler. Any character may appear in the comment field, with the obvi¬ 
ous exception of the newline character, which starts a new line. 

A |- line switches listing off. A |+ line switches listing on. 
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3. SYMBOLS AND EXPRESSIONS 

This section describes the various components of a68 expressions: sym¬ 
bols, numbers, terms, and expressions. 


3.1. Symbols 

A symbol consists of a sequence of characters, with the following restric¬ 
tions: 

1. Valid characters include A-Z, a-z, 0-9, period (.), underscore (_), and 
dollar sign (S). 

2. The first character must not be numeric. 

All characters are significant and are checked in comparisons with other 
symbols. Upper and lower cases are distinct, (''One” and "one" are 
separate symbols). 

A symbol is declared when the assembler recognizes it as a symbol of the 
program. A symbol is defined when a value is associated with it. With the 
exception of symbols declared by a .globl directive, all symbols are defined 
when they are declared. A label symbol (which represents an address of 
the program) may not be redefined; all other symbols are allowed to 
receive a new value. 

There are several ways to declare a symbol: 


1. As the label of a statement (See section 2.1). 

2. In a direct assignment statement. 

3. As an external symbol via the .globl directive. 

4. As a common symbol via the .comm directive. 

5. As a local symbol. 

3.2. Direct Assignment Statements 

A direct assignment statement assigns the value of an arbitrary expres¬ 
sion to a specified symbol. The format of a direct assignment statement is: 

symbol ~ expression 

Examples of valid direct assignments are: 
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vect_size = 4_ 

▼ectora = OxFFFE 

vectorb = vectora - Tect^_mze 

CRLF = OzODOA 

Only one symbol may be assigned in a single statement. 

Any symbol defined by direct assignment may be redefined later in the 
program, in which case its value is the result of the last such statement. A 
local symbol may be defined by direct assignment, though this doesn’t 
make much sense. Label or register symbols may not be redefined. 

If the expression is absolute, then the symbol is also absolute, and may be 
treated as a constant in subsequent expressions (see section 3.4). If the 
expression is relocatable, however, then the symbol is also relocatable, 
and it is considered to be declared in the same program section as the 
expression. See section 3.7 for an explanation of absolute and relocatable 
expressions. 

If the expression contains an external symbol, then the symbol defined by 
the = statement will also be considered external. For example: 

.globl x | x is declared as external symbol 
sum = x | sum becomes an external symbol 

assigns the value of x (zero if it is undefined) to sum and makes sum an 
external symbol. External symbols may be defined by direct assignment. 


3.3. Register Symbols 

Register symbols are symbols used to represent registers in the machine. 
Register symbols are defined in the source descriptor file for a machine in 
the pre-assembly code portion of the file. This portion consists of source 
statements that are assembled before every source program for the 
machine. 

The following symbols are register symbols. 


dO 

dl 

d2 

d3 

d4 

d5 

d6 

d7 

aO 

al 

a2 

a3 

a4 

aS 

a6 

a7 

sp 


cc 

sr 

usp 





3.4. External Symbols 

A program may be assembled in separate modules, and then linked 
together to form a single program (see Id (I)). External symbols may be 
defined in each of these separate modules. A symbol which is declared 
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(given a value) in one module may be referenced in another module by 
declaring the symbol to be external in both modules. There are two forms 
of external symbols: those defined with the .globl and those defined with 
the .comm directive. 

External symbols are declared with the .globl assembler directive. The 
format is: 

.globl symbol [, symbol] ... 

For example, the following statements declare the array TABLE and the 
routine SRCH to be external symbols: 

.globl TABLE,SRCH 
TABLE: .=.+20 
SRCH: movl fTABLE.aO 


External symbols are only declared to the assembler. External symbols 
must be defined (i.e. given a value) in some other statement by one of the 
methods mentioned above. They need not be defined in the current pro¬ 
gram; in this case they are flagged as "undefined" in the symbol table. If 
they are undefined, they are considered to have a value of zero in expres¬ 
sions. 

The other form of external symbol is defined with the .comm directive. 
These statement reserve storage in the bss section similar to FORTRAN 
common areas. The format of the statement is: 

.comm name. ConstantExpression 

which causes a68 to declare the name as a common symbol with a value 
equal to the ConstantExpression. For the rest of the assembly this symbol 
will be treated as though it was an undefined global. a68 does not allocate 
storage for common symbols; this task is left to the loader. The loader will 
compute the maximum size of for each common symbol which may appear 
in several load modules, allocates storage for it in the final bss section and 
resolves linkages. 


3.5. Local Symbols 

Local symbols provide a convenient means of generating labels for branch 
instructions, etc. Use of focal symbols reduces the possibility of multiply- 
defined symbols in a program, and separates entry point symbols from 
local references, such as the top of a loop. Local symbols cannot be refer¬ 
enced by other object modules. 
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Local symbols are of the form nS where n is any integer. The following are 
valid local symbols 

IS 

27S 

394S 

A local symbol is defined and referenced only within a single "local symbol 
block" (lsb). A new local symbol block is entered when: 

1. a label is declared; or, 

2. a new program section is entered. 

There is no conflict between local symbols with the same name which 
appear in different local symbol blocks. 


3.6. Assembly Location Counter 

The assembly location counter is the period character, V; hence its name 
"dot". When used in the operand field of any statement, dot represents the 
address of the first byte of the statement. Even in assembly directives, it 
represents the address of the start of the directive. A dot appearing as the 
third argument in a .byte instruction has the value of the address where 
the first byte was loaded; this address is not updated "during" the 
pseudo-op. 

For example, 

Ralph: movl ..aO [load value of this instruction into aO 

At the beginning of each assembly pass, the assembler clears the location 
counter. Normally, consecutive memory locations are assigned to each 
byte of generate code. However, the location where the code is stored may 
be changed by a direct assignment altering the location counter: 

. = expression 

This expression must not contain any forward references, and must not 
change from one pass to another. Storage area may also be reserved by 
advancing dot. For example, if the current value of dot is 1000, the direct 
assignment statement: 

Table: .=.+100 

would reserve 100 (decimal) bytes of storage, with the address of the first 
byte as the value of Table. The next instruction would be stored at address 
1100. 
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3.7. Program Sections 

As in UNIX, programs to a68 are divided into three sections: text, data and 
bss. The normal interpretation of these sections is: instruction space, ini¬ 
tialized data space and uninitialized data space, respectively. These three 
sections are equivalent as far as a68 is concerned with the exception that 
no instructions or data will be output for the 6ss section although its size 
will be computed and its symbol values will be output. 

In the first pass of the assembly, a68 maintains a separate location 
counter for each section, thus for code like: 

.text 

stun: movw dl,d2 
.data 

hello: .long 27 
.text 

jnk: addw d2,dl 
.data 

myst: .byte 4 

in the output, sum will immediately precede jnk and hello will immediately 
precede myst. At the end of the first pass, a68 rearranges all the 
addresses so that the sections will be output in the following order: text, 
data and bss. The resulting output file is an executable image file with all 
addresses correctly resolved, with the exception of undefined .globls and 
.comms. For more information on the format of the output file, consult 
the UNIX man entry on a.out files. 


3.8. Constants 

All constants are considered absolute quantities when appearing in an 
expression. 


3.8.1. Numeric Constants 

An a68 numeric constant is a sequence of digits. a68 interprets 
integers as octal, hex, or decimal according to the following conven¬ 
tions. 


octal octal numbers begin with 0 

hex hex numbers begin with Ox or OX 

decimal all other numbers 
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3.9. Operators 

3.9.1. Unary Operators 

There are two unary operators in a68: 

unary minus. 

~ _ logical negation. 

3.9.2. Binary Operators 

Binary operators in a68 include: 


+ Addition; e.g. "3+4" evaluates to 7. 

S ubtraction; e.g. "3-4" evaluates to -1., or 

OxFFFFFFFF 

_ Multiplication; e.g. "4*3" evaluates to 12. _ 

Each operator is assumed to work on a 32-bit number. 


3.10. Terms 

A term is a component of an expression. A term may be one of the follow¬ 
ing: 


1. A number. 

2. A symbol. 

3. A term preceded by a unary operator. For example, both "sum" and 
"~sum” may be considered to be terms. Multiple unary operators are 
allowed; e.g. " — A" has the same value as "A". 


3.11. Expressions 

Expressions are combinations of terms joined together by binary opera¬ 
tors. An expression is always evaluated to a 32-bit value. If the instruction 
calls for only one byte, (e.g. .byte), then the low-order byte is used. 

Expressions are evaluated left to right with no operator precedence. Thus 
”1+2*3" evaluates to 9, not 7. Unary operators have precedence over 
binary operators since they are considered part of a term, and both terms 
of a binary operator must be evaluated before the binary operator can be 
applied. 
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A missing expression or term is interpeted as having a value of zero, 
this case, an "Invalid expression" error will be generated. An "Invalid 
Operator" error means that a valid end-of-line character or binary opera¬ 
tor was not detected after the assembler processed a term. In particular, 
this error will be generated if an expression contains a symbol with an ille¬ 
gal character, or if an incorrect comment character was used. 

Any expression, when evaluated, is either absolute, relocatable, or exter¬ 
nal: 

a. An expression is absolute if its value is fixed. An expression whose 
terms are constants, or symbols whose values are constants via a 
direct assignment statement, is absolute. A relocatable expression 
minus a relocatable term, where both items belong to the same pro¬ 
gram section is also absolute. 

b. An expression is relocatable if its value is fixed relative to a base 
address, but will have an offset value when it is linked, or loaded into 
core. All labels of a program defined in relocatable sections are relo¬ 
catable terms, and any expression which contains them must only 
add or subtract constants to their value. For example, assume the 
symbol "sum" was defined in a relocatable section of the program. 
Then the following demonstrates the use of relocatable expressions: 


sum 

relocatable 

sum+5 

relocatable 

sum *2 

Not relocatable (error) 

2-sum 

Not relocatable (error), since the expression 

sum-jnk 

cannot be linked by adding sum’s offset to it. 
Absolute, since the offsets added to sum and jnk 

cancel each other out. 


An expression is external (or global) if it contains an external symbol 
not defined in the current program. The same restrictions on expres¬ 
sions containing relocatable symbols apply to expressions containing 
external symbols. Exception: the expression sum-jnk where both sum 
and jnk are external symbols is not allowed. 
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4. INSTRUCTIONS AND ADDRESSING MODES 

This section describes the conventions used in a68 to specify instruction 
mnemonics and addressing modes. 


4.1. Instruction Mnemonics 

The instruction mnemonics used by a68 are described in the previously 
mentioned Motorola manual with a few variations. Most of the 68000 
instructions can apply to byte, word on long operands, so in a68 the nor¬ 
mal instruction mnemonic is suffixed with b, w, or 1 to indicate which 
length operand was intended. For example, there are three mnemonics 
for the or instruction: orb, orw and orl. Op-codes for instructions with 
unusual opcodes may have additional suffixes, thus in addition to the nor¬ 
mal add variations, there also exist: addqb, addqw and addql for the add 
quick instruction. 

Branch instructions come in two flavors, byte and word. In a68, the byte 
(i.e., short) version is specified by appending the suffix a to the basic 
mnemonic as in beq and begs. 

In addition to the instructions which explicitly specify the instruction 
length, &68 supports extended branch instructions, whose names are gen¬ 
erally constructed by replacing the b with j. If the operand of the 
extended branch instruction is a simple address in the current segment, 
and the offset to that address is sufficiently small, &68 will automatically 
generate the corresponding short branch instruction. If the offset is too 
large for a short branch, but small enough for a branch, then the 
corresponding branch instruction is generated. If the operand references 
an external address or is complex, then the extended branch instruction 
is implemented either by a jmp or jsr (torjra or jbsr), or by a conditional 
branch (with the sense of the conditional inverted) around a jmp for the 
extended conditional branches. In this context, a complex address is 
either ain address which specifies other than normal mode addressing, or 
relocatable expressions containing more than one relocatable symbol, i.e. 
if a, b and c are symbols in the current segment, then the expression 
a+b-c is relocatable, but not simple. 

Note that a68 is not optimal for extended branch instructions whose 
operand addresses the next instruction. The optimal code is no instruc¬ 
tion at all, but a68 currently retains insufficient information to make this 
optimization. The difficulty is that if a68 decides to just eliminate the 
instruction, the address of the next instruction will be the same as the 
address of the (nonexistent) extended branch instruction. This instruc¬ 
tion will then look like a branch to the current location, which would 
require an instruction to be generated. The code that a68 actually gen¬ 
erates for this case is a nop (recall that an offset of zero in a branch 
instruction indicates a long offset). Although this problem may arise in 
compiler code generators, it can easily be handled by a peephole 
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optimizer. 

The algorithm used by a68 for deciding how to implement extended 
branch instructions is described in “Assembling Code for Machines with 
Span-Dependent Instruction," by Thomas G. Szymanski in Communications 
of the ACM, Volume 21, Number 4, pp300-308, April 1978. 

Consult the appendix for a complete list of the instruction op-codes. 


4.2. Addressing Modes 

The following table describes the addressing modes recognized by a68. In 
this table an refers to an address register, dn refers to a data register, Ri 
to either a data or an address register, d to a displacement, which, in a68 
is a constant expression, and xxx to a constant expression. Certain 
instructions, particularly move accept a variety of special registers 
including sp, the stack pointer which is equivalent to a7, sr t. the status 
register, cc, the condition codes of the status register, usp, the user mode 
stack pointer, and pc, the program counter. 


Mode 

Notation 

Example 

Register 

an.dn.sp.pc.cc.sr.usp movw a3,d2 

Register Deferred 

an© 

movw a3@,d2 

Postincrement 

an@+ 

movw a3@+,d2 

Predecrement 

an@- 

movw a3©-,d2 

Displacement 

an©(d) 

movw a3@(24),d2 

Word Index 

an@(d, Ri:W) 

movw a3@(l6, d2fW),d3 

Long Index 

an@(d, Ri:L) 

movw a3@(l6, d2:L),d3 

Absolute Short 

xxx:W $ 

movw 14:W,d2 

Absolute Long 

xxx.L 

movw 14:L,d2 

PC Displacement 

pc@(d) 

movw pc@(20),d3 

PC Word Index 

pc@(d, Ri:W) 

movw pc@(14, d2:W),d3 

PC Long Index 

pc@(d, Ri:L) 

movw pc@(14, d2:L),d3 

Normal 

sun 

movw sun,d3 

Immediate 

#xxx 

movw #27+3,d3 


Normal mode actually assembles as absolute long, although the value of 
the constant will be flagged as relocatable to the loader. The notation for 
these modes derived from the Motorola notation with the exception of the 
colon in index mode rather than period. 

The Motorola manual presents different opcodes for instructions that use 
the effective address as data rather than the contents of the effective 
address such as adda for add address. a68 does not make this distinction 
because it can determine the type of the operand from its form. Thus an 

t The access to sr is restricted to specific 68000 instructions. 

% MUNIX LD(1) does not support short external addresses 
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instruction of the form: 

sun: .word 0 

• •• 

addl fsun.aO 

will assemble to the add address instruction because sun is known to be 
an address. 

The 68000 tends to be very restrictive in that most instructions accept 
only a limited subset of the address modes above. For example, the add 
address instruction does not accept a data register as a destination. a68 
tries to check all these restrictions and will generate the illegal operand 
error code for instructions that do not satisfy the address mode restric¬ 
tions. 


13 


March 5,1984 


13 



a 68 


- 14 - 


a68 


5. ASSEMBLER DIRECTIVES 


The following pseudo-ops are available in a68: 



stores character strings 


.byte 

.word 

•long 

.zerol 

.text 

.data 

.bss 

.globl 


.comm 


.extern 


stores 8-bit bytes 
stores 16-bit words 
stores 32-bit longwords 
long zeroes 
Text csect 
Data csect 
Bss csect 

declares external symbols 
same as .globl 
declares common symbols 


5.1. .ascii .asciz 

The .ascii directive translates character strings into their 7-bit ascii 
(represented as 8-bit bytes) equivalents for use in the source program. 
The format of the ascii directive is as follows: 

.ascii "character string" 

The syntax of C-strings is used (\ n is newline, etc.). Obviously, a newline 
must not appear within the character string. 

The .asciz directive is equivalent to the .ascii directive with a zero byte 
automatically inserted as the final character of the string. Thus, when a 
list or text string is to be printed, a search for the null character can ter¬ 
minate the string. 


5.2. .byte .word .long 

The .byte, .word and .long directives are used to reserve bytes and words, 
and to initialize them with certain values. 

The format is: 

[label:] .byte [expression] [.expression] . . 

[label:] .word [expression] [.expression] .. 

[label:] .long [expression] [.expression] .. 


14 


March 5, 1984 


14 





a 68 


15- 


a68 


For example, the first statement reserves one byte for each expression in 
the operand field, and initializes the value of the byte to be the low-order 
byte of the corresponding expression. Note that multiple expressions must 
be separated by commas. A blank expression is interpreted as zero, and 
no error is generated. 

The syntax and semantics for .word is identical, except that 16-bit words 
are reserved and initialized, of course, and .long uses 32-bit quantities. 


5.3. .text .data .bss 

These statements change the "program section" where assembled code 
will be loaded. 

5.4. .globl .comm 

See section 4.4. 


5.5. .even 

This directive advances the location counter if its current value is odd. 
This is useful for forcing storage allocation like .word directives to be on 
word boundaries. 
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6. ERROR CODES 

If an error is detected during assembly, a message of the form: 
line_no .error_code 

is output to the standard error stream. 

The following .error_cocfes, and their probable cause, appear below: 

2 Invalid Character. An invalid character for a character constant or 
character string was encountered. 

3 Multiply defined symbol. A symbol appears twice as a label, or an 
attempt to redefine a label using an = statement. 

4 Symbol storage exceeded. No more room is left in the symbol table. 
Assemble portions of the program separately, then bind them together. 

6 Symbol length exceeded. A symbol of more than 31 characters was 
encountered. 

7 Undefined symbol. A symbol not declared by one of the methods men¬ 
tioned above in ’Symbols’ way encountered. This happens when an 
invalid instruction mnemonic is used. This also occurs when an invalid or 
non-printing character occurs in the statement. 

8 Invalid Constant. An invalid digit was encountered in a number. 

9 Invalid Term. The expression evaluator could not find a valid term: sym¬ 
bol, constant or expression. An invalid prefix to a number or a bad sym¬ 
bol name in an operand will generate this. 

10 Invalid Operator. Check the operand field for a bad operator. 

11 Non-relocatable expression. If an expression contains a relocatable sym¬ 
bol (e.g. label) then the only operations that can be applied to it are the 
addition of absolute expressions or the subtraction of another relocat¬ 
able symbol (which produces an absolute result). 

12 Invalid operand type. The type field of an operand is either not defined 
for the machine, or represents an addressing mode incompatible with 
the current instruction. 

13 Invalid operand. This is a catch-all .error. It appears notably when an 
attempt is made to assign an undefined value to dot during pass 1. 

14 Invalid symbol. If the first token on the source line is not a valid symbol 
(or the beginning of a comment), this is generated. Might happen if you 
try and implied .word. 

15 Invalid assignment. An attempt was made to redefine a label with an = 
statement. 
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16 Too many labels. More than 10 labels and/or symbols ’s appeared on a 
single statement. 

17 Invalid op-code. An op-code mnemonic was not recognized by the assem¬ 
bler. 

18 Invalid entry point. The entry point of the program (declared on the .end 
statement) must be a defined label. 

19 Invalid string. An invalid string for .ascii or .asciz was encountered. 
Make sure string is enclosed in double quotes. 

20 Bad filename or too many levels. An invalid filename was given to .insrt, 
or there were more than 10 levels of nested .insrts. 

22 .error statement. An .error statement was encountered during pass 2. 

25 Wrong number of operands. This is usually a warning. Check the 
manufacturer’s assembly manual for the correct number of operands 
for the current instruction. 

26 Line too long. A statement with more that 132 characters before the 
newline was encountered. 

27 Invalid register expression. Any expression inside parentheses should be 
absolute and have the value of a register code (register symbols). This 
may occur if you use parentheses for anything other than the register 
portion of an operand. 
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7. Appendix 


OpCode 

Description 


OpCode 

Description 


abed 

add decimal with extend 


movepl 

move peripheral 

addL 

add 



movepw 

move peripheral 

addqL 

add quick 


moveq 

move quick 


addxL 

add extended 


muls 

signed multiply 

andL 

and 



mulu 

unsigned multiply 

aslL 

arithmetic shift left 


nbed 

negate decimal with extend 

asrL 

arithmetic shift right 


negL 

negate binary 


bCCS 

branch on condition 


negxL 

negate binary with extend 

bchg 

test a bit and change 


nop 

no operation 


bclr 

test a bit and clear 


notL 

logical compliment 

bra 

branch 


orL 

inclusive or 


bset 

test a bit and set 


pea 

push effective address 

bsrS 

subroutine branch 


reset 

reset machine 

btst 

test a bit 


rolL 

rotate left 


chk 

check register against bounds 


rorL 

rotate right 


clrL 

clear an operand 


roxlL 

rotate left with extend 

cmpL 

compare 


roxrL 

rotate right with extend 

empmL 

compare memory 


rte 

return from exception 

divs 

signed divide 


rtr 

return and restore codes 

divu 

unsigned divide 


rts 

return from subroutine 

eorL 

exclusive or 


sbed 

subtract decimal with extend 

cxg 

exchange registers 


sCC 

set on condition 

extl 

sign extend 


Bf 

set all zeros 


extw 

sign extend 


St 

set all ones 


jbsr 

jump to subroutine 


stop 

halt machine 


jCC 

jump on condition 


subL 

subtract 


jra 

jump 



subqL 

subtract quick 

jsr 

jump to subroutine 


subxL 

subtract extended 

lea 

load effective address 


swap 

swap register halves 

link 

link 



tas 

test operand then set 

islL 

logical shift left 


trap 

trap 


IsrL 

logical shift right 


trapv 

trap on overflow 

movL 

move 



tstL 

test operand 


move ml 

move 

multiple registers 


unlk 

unlink 


movemw move multiple registers 




Where: 








S Short branch 




s short 






lone branch 
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CC Condition Code 

cs 

carry set 

eq 

equal 

ra 

inconditional 

ge 

greater or equal 

gt 

greater than 

hi 

high 

le 

less or equal 

Is 

lower or same 

It 

less than 

mi 

minus 

ne 

not equal 

Pi 

positive 

VC 

no overflow 

vs 

overflow set 


LLencth 

b 

byte 

w 

word 

1 

_long_ 
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ABSTRACT 
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assembly programs on 68000 UNKT systems. The assembler is 
upward compatible with the M68000 Cross Macro assembler pro¬ 
vided by Motorola. This guide restricts itself therefore to describ¬ 
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The Assembler 68000 is a modified version of the CERN Cross 
Macro Assembler M68M1L implemented in Pascal. Changes were 
made to write a.out format (the object module format co m i ng with 
UNK ) instead of CUFOM (CERN Universal Format for Object 
Modules). 
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1. INTRODUCTION 

The Cross Macro Assembler described in this manual is derived from the CERN 
Cross Macro Assembler M63MIL but writes a.out object format instead of CUFOK. 
Some of the pseudo instructions were changed to provide the user with a means 
to control a.out segments instead of CUFOM sections. All other pseudo instruc¬ 
tions all machine instructions and the expression rules - as far as symbol types 
are not concerned - are the same as for M68MIL and Motorola's Cross Assem¬ 
bler. 

The assembler translates assembler source programs for the Motorola 68000 
microprocessor into a.out. the format of UNIX loadable modules. A linkage editor 
subsequently allows the combination and linking of several such modules into a 
mew ajout module. An archiver (see ar(l)) permits the construction of a.out 
libraries, which can be placed in the input to the linkage editor. Besides, the 
•assembler will accept source flies 'piped' through the UNIX preprocessor cpp. 

The assembler is upward compatible with the M68000 Cross Macro Assembler 
provided by Motorola. Additional pseudo instructions are provided tc.allow the 
generation of relocatable object modules. The user is advised to see the follow¬ 
ing Motorola publications: 

M68000 Cross Macro Assembler Reference Manual 
E68KXASK(D3). Third Edition, September 1979 

MC68000 16-Bii Microprocessor. User’s M anual 
MC68000UM(AD2), Second Edition. January. 1980 

and the UNIX documentation 

UNIX Programmer's Manual, Volume 1 (especially ar(l), ld(l), a.out (5) ) 

*c a base for the use of this assembler. This manual will restrict itself to the 
description of the extensions made to the definitions of the Motorola cross 
assembler. For the readers’ convenience this will be done in complete chapters 
Tather than by listing the explicit differences. 

•The areas covered by this note are: 

Short description of a. out 
Expressions (generalized) 

Pseudo instructions 
Macro definitions 
How to use the assembler 

•Acknowledgement: 1 would like to thank Mr. Horst von Eicken who gave us the 
Pascal sources and user manual of his CERN Cross Assembler. L you 
interested in this assembler, please contact him at: 

Horst von Eicken 
Data Handling Division 
CERN 

CH 1211 Geneva 23 
Switzerland 
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2. SHORT DESCRIPTION OF a^>ut 

In a.out modules code and data fall into three segments: the text segment, the 
data segment and the bss segment. The text segment is the one in which the 
assembler begins, and it is the one into which instructions are typically placed. 
The "UNIX system can enforce the purity of the text segment of programs by 
trapping write operations into it (see ld(l)). 

The data, segment is available for placing data or instructions which will be 
modified during execution. Anything which may go in the text segment may be 
put into the data segment. In programs with write-protected, shareable text 
segments, data segment contains the initialized but variable parts of a program. 

The bss segment may not contain any explicitely initialized code or data. The 
length of the bss segment (like that of text or data) is determined by the high- 
water mark of the location counter within it. At the start of execution of a pro¬ 
gram. the bss segment is set up by statements such as: 

lab dal 2 

Another a.out convention concerns the entry point to a program: a program 
starts at a label —entry (which is typically defined by some runtime system and 
does some basic initialization) and branches then to a user-defined label - m ain. 
The user to make sure that one and only one .main label is defined within 
her/his program 

Since a.out modules are always relocatable it is not possible in an a.out 
module to allocate a label (symbol) at a certain absolute address - as it can 
be reached elsewhere by means of an org pseudo instruction - rather than 
by arranging the link-edlt input appropriately (see ld(l)). org is supported 
lor compatibility but it’s limited. 
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3.1. Symbols 

Symbols recognized by the assembler consist of one or more characters, the 
•first sixteen of which are significant. The first character must be a letter 
(a through z ;and A through Z) or an underscore (4. each remaining character 
may'be a letter, a digit (0 through 9) or an underscore. The names for registers 
(a0 through a?. dO through d7 t sp,usp t ccr^r ), instructions (abed - u ni n k) and 
pseudo instructions (blong ~ ttl) are predefined symbols and may not be 
redefined bythe user. 

a »nd A are different; predefined names must be written in lower case. 

Numbers' recognized by the assembler include decimal, hexadecimal and octal 
■values. Decimal numbers are specified by a string of decimal digits (0 through 
S): hexadecimal numbers are specified by a dollar sign (S). followed by a string 
of hexadecimal digits (0 through 9. A through F, a through f); octal numbers are 
specified by a colon (:), followed by a string of octal digits (0 through 7). 

One or more characters enclosed by apostrophes (’) constitute a character 
string. Character strings are left-adjusted and zero-filled (if necessary), 
whether .stored or used as immediate operands. Only strings of four or fewer 
characters may be used as immediate operands. (In order to specify an apos¬ 
trophe within a character string, two successive apostrophes must appear 
where the single apostrophe is intended to appear.) 

The assembler has six types of symbols: 
absolute symbol: 

1. The symbol is equated ( equ) or set to an absolute value. 

2 . The symbol is equated ( equ ) or set to a co ns t an t. Its value is un a ff ected 
by any possible future applications of the link- editor to the module. 

text symbol: 

1 . The sym bol is equated ( equ ) or set to a text symbol. 

2. The symbol is defined in the text segment of the program Its value is 
measured with respect to the beginning of the text segment of the pro¬ 
gram If the assembler output is link-edited, its text symbols may change in 
value since the module need not be the first in the link editor's output. At 
Ihe start of an assembly the value of is text 0. 

data symbol: 

1. The sym bol is equated ( equ ) or set to a data symbol. 

2. The symbol is defined in the data segment of the program Its value is 
measured with respect to the beginning of the data segment of the pro¬ 
gram If the assembler output is link-edited, its data symbols may change 
dn value since the module need not be the first in the l ink editor's output. 
After the first data pseudo instruction the value of is data 0. 
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bss symbol: 

1 . The symbol is equated ( equ) or set to a bssisymbol. 

2. The symbol is defined in the bss segment of the program. Its value is meas¬ 
ured with respect to the beginning of the bss segment of the program Like 
text and data symbols, the value of a bss symbol may change during a sub¬ 
sequent link-editor run. since previously loaded programs may have bss 
•segments. After the first bss pseudo instruction the value of "•*' is bss 0. 

external symbol: 

The symbol is listed in a extern pseudo Instruction and Is not defined in the 
current assembly. Its value is set to zero and must be defined during a sub¬ 
sequent link-editor run. 

‘undefined, symbol: 

The symbol is neither defined in the current .assembly nor listed in an 
extern pseudo instruction. The occurrence of such a symbol is indicated as 
an error. 

All symbols exceot absolute symbols are relative, i.e. they represent relocatable 
addresses. Whenever the assembler encounters a text, data, or bss symbol it will 
generate a direct address (see below) and related relocation information. To 
yield a program counter relative address write 

< 3 *sym>(pc) or 
<rsym>(pc,<reg>) 

respectively.- 

Symbols defined within an assembly as absolute, text, data, or bss symbol may 
be exported by occurring in a entry pseudo instruction. i.e. their value.and 
their type are available to the link-editor so that the program may be loaded 
with others that reference these symbols. 


3.2. Expressions 

An expression is a combination of symbols, constants, algebraic operators, and 
parentheses. The expression is used to specify a value which Is to be used as an 
operand. Expressions follow the conventional rules of algebra. 

Expressions may contain relative symbols. However the following rules must be 
followed in order for the expression, to be valid: 

1 . Relative symbols or expressions cannot be multiplied, divided, added, or 
operated on with the logical operators. 

2. A relative symbol or expression may have an absolute value added to or 
subtracted from it. The result Is relative. 

3. A relative symbol or expression may be subtracted from another relative 
symbol or expression provided they are both defined and of same type. The 
result is absolute. 

3.3. Direct Addressing 

(The addressing mode discussed here is called 'absolute addressing mode in 
the related Motorola documentation. Since those address values cannqt^be 
• changed at run time, but may be changed during a link-edit run. t hey are 
referred to here as direct addresses to avoid confusion with absolute symbols 
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defined ealier in this manual.) 

Since the M $8000 microprocessor allows two forms of direct addressing. 

- short direct address (16 bit address) * 

- long direct address (32 bit address) - 

the assembler has to take a decision as to which form to assume whenever it 
encounters a forward referenced absolute symbol. Le. a symbol which has not 
yet been defined, or a relative symbol. Le. a symbol the value of which may be 
Ranged by the link-editor. By default it will use the long direct address to 
e£Se correct handling of the symbol. The pseudo instructions 
♦,.rt data and bss will allow the programmer to override the assembler defaults. 
Resembling external-symbols it will always use the long direct address mode. 

A similar problem exists for branches. If a forward reference is Jound in a 
branch instruction, the assembler will use the two-word form of the instruction. 
llsins the suffix .s for the branch instruction the progr amm er can force the 
assembler to generate the one-word form of the branch instruction. The pseu o 
instructions bshort and blong allow additional control. 
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4. PSEUDO INSTRUCTIONS 

Pseudo Instructions discussed in this chapter are classified according to appli¬ 
cation as follows: 

Module identification (ident, end) 

Segment control (text, data, bss) 

Symbol definition (equ, set) 

Module linkage (entry, extern) 

Data generation and storage reservation (dc, ds, org; 

Conditional assembly (else, endc, cn di f . tfeq, line) 

Source stream control ( ins e r t) 

Toting control (list^molist,page,nopage.sttLt±Uail) 

Object code control (blong. bshort, flong. fshort, noobj) 

Cross reference control (xrefon. xrefofl) 


The next chapter describes the definition and use of macros. The format 
description for the pseudo instructions uses symbols which have the following 
syntactical meaning: 

Enclose optional fields of the pseudo instruction. 

<.> Enclose a 'syntactic variable', e.g. <number>. 

4 . 1 . Module Identification 

4 . 1 . 1 . IDENT - Module Identification 

For compatibility with M68MIL an ident pseudo instruction is accepted but is 
ignored. It has the following format: 

ident . <symbol> 

<symbol> 

Th& symbol defines & name (orig in ally that of the module). 


4.1.2. END - Tfrid of liodule 

An end pseudo instruction must be the last instruction of each module. It 
causes the assembler to terminate all counters, conditional assembly, or macro 
generation. It also causes the a.out module to be terminated. 

end [<symbol>J 

<symbol> , 

An optional s ym bol is accepted • for compatibility - but ignored. The pro¬ 
gram entrypoint is determined by the label - m a in as stated in the 

a.out description. 

42. Segment Control 

Segment control pseudo instructions allow the programmer to divide a source 
module into separately controlled regions of a program, providing her/him with 
a means of changing type and value of the location counter. They start or 
resume assembly for one of the three a.out segments. The segment in use is the 
segment into which code is subsequently assembled. By default the assembler 
will always start with the text segment using long direct address mode (see 3.3). 
If the s uffix j is appended to a segment control pseudo instruction, the assem¬ 
bler will assume that this segment will Anally be loaded into low address 
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memory and use direct short addresses for backward references, 
ar- The suffix 3 does not imply that forward references in that segment will 
als o be resolved with direct short addresses, fshort must be used for this 
purpose. 


4.2.1. Text Segment 

textjjj 

Description: 

The pseudo instruction causes the assembler to start or resume assembly 
in the text segment. 


4.2.2. Data Segment 

detail 

Description: 

The pseudo instruction causes the assembler to start or resume assembly 
in the data segment. 


4iL3. Bss Segment 

bss(.si 

Description: 

The pseudo instruction causes the assembler to start or resume storage 
allocation in the bss segment (uninitialised data: ds and org only). 


4.3. Symbol Definition 
4.3.1. EQU - Equate Symbol Value. 
<symbol> equ <expression> 


<symbol> 

A location symbol following the naming rules must be defined. 

<expression> , , 

An expression following the expression rules. Forward references are not 

allowed. 


Description: , . , 

An equ pseudo instruction permanently defines the symbol in the location 
field as paving the value and type indicated by the expression in the vari¬ 
able field. 


4 .3.2. SET - Set or reset symbol value. 
<symbol> set <expression> 
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<symboi> 

A location symbol following the naming rules must be defined. 

<e xpr c s s i on> 

An expression following the expression rules. Forward references are not 
allowed. 

Description: 

A set pseudo instruction defines the symbol in the location field as having 
the value and type indicated by the expression In the variable field. A sub¬ 
sequent set using the same symbol redefines the symbol to the new value 
•and type. 

4.4. Module Linkage 

The pseudo instructions entry and extern do not define symbols but either 
declare symbols defined within a module as being available outside the module 
or declare symbols referred to in the module as being defined outside the 
module. 

4.4.1. ENTRY - Declare Entry Symbols 


entry <symj>. <sym 2 > .... <sym 3 > 


<sym> 


Linkage symbol. Each symbol must be defined in the module as nonexter¬ 
nal (must'not be listed on an extern pseudo instruction). 

Description: ...... ... .. 

The entry pseudo instruction specifies which of the symbolic addresses 
defined in the module can be referred to by modules assembled indepen¬ 
dently*. entry lists entry points to the current module. 


4.4.2. EXTERN - Declare External Symbols 

extern <sym l > . <sym 2 > .... <sym n > 

<sym i > 

Linkage symbol. These symbols must not be defined within the module. 
Description: 

The extern pseudo instruction lists symbols that are defined as entry 
points in independently assembled modules for which references can 
appear in the module being assembled. 

4.5. Data Generation and Storage Reservation 
4.5.1. DC - Define Constant 


{<symbol>l 

l<symboi>$ 

f<symbol>$ 

j<symbol>J 


dc <oprj>. <opr 2 > .... <opr a > 
dc.b <opr J >. <opr 2 >.... <opr a > 
dc.w <oprj> . <opr 2 > .... <opr a > 
dcJ. <opr^>. <opr 2 >.... <opr a > 
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<symbol> 

A symbol following the naming rules may be defined. 

<oprj> 

The operand can be a symbol, an ascii, decimal or hexadecimal value or an 
expression evaluating to such a value. 

Description: 

The function of the dc pseudo instruction is to define a constant in 
memory. The dc directive may have one operand, or multiple operands 
which are separated by commas. The operand field may contain a value 
^decimal. octal, hexadecimal, or character string), a symbol or a -expres¬ 
sion. The constant is aligned on a word boundary if word( .w) or long ( .1) is 
specified, or a byte boundary if byte ( .b) is specified. The constant is lim¬ 
ited to 60 bytes. 

The following rules apply to size specifications on character strings: 

dc.b If an odd number of bytes (characters) are entered, the odd byte on the 
right will be zero filled unless the next source statement is another dc.b 
or ds.b. In this case the next dc.b or ds.b will start in the odd byte on the 
right. 

dc.w If an odd number of bytes (characters) are entered, the last word will be 
zero filled on the right to force an even byte count. 
dc.l If less than a multiple of four bytes are entered, the last long word will be 
zero filled.on the right to a multiple of four, bytes. 

4.5.2. DS - Define Storage 

|<symbol>J ds <expression> 

|<symbol>j ds.b <expression> 

j<symbol>j ds.w <expression> 

|<symbol>j dsi <expression> 

<symbol> 

A symbol following the naming rules may be defined. 

<expression> 

The expression must evaluate to an absolute, positive value. 

. Description: 

The ds pseudo instruction is used to reserve memory locations. The con¬ 
tents of the memory reserved are zero filled for text and data segment, for 
bss segment they are not initialized in anyway. The expression must evalu¬ 
ate to an absolute value. Forward references are not allowed. 


4 .5.3. ORG-Origin 

Since a.out modules are always relocatable the org pseudo instruction is appli¬ 
cable only in a very restricted manner: it can be used to advance the location 
counter a certain number of bytes or to a certain label. The skipped locations 
are zero filled. 


tsrg <expression> 






Description: 

The org pseudo instruction is used to advance the location counter 
<expression> bytes. It's identical with 

ds.b <e:cpre ssion> • 

i.e. the expression must be of current segment type and evaluate to an 
value greater than the actual location counter. 


-4.6. Conditional Assembly 

The pseudo Instructions ifeq and ifne permit optional assembly or skipping of 
source code. The instructions immediately following the test instruction are 
assembled if the tested condition is true and skipped if the condition is false. 
Skipping is terminated either by a source statement count on the if instruction, 
or by an endil. else or an end. The statement count, when used, is decremented 
for instruction lines only; comment lines (identified by * in column one) are not 
counted. 

The result of an if test is determined by the value of the expression in pass one 
of the assembler; the value of a relative symbol is relative to the origin of the 
segment in which it was defined. The value of an external symbol is zero if the 
symbol was declared as external. If. the symbol was defined relative to a 
declared external, the value is the relative value, if s may be nested up to ten 
levels deep. 


4.6.1. ENDIF - End of IF Range 
{<if_name>J endif 

<f_name> 

An optional symbol; defines the name of an ifeq. ifne or else sequence; or 
blank. 

Description: 

An endif pseudo instruction (or endc for compatibility with the Motorola 
assembler) causes termination of skipping and assembly to resume. When 
the sequence containing the endif is being assembled, or is controlled by a 
statement count, the endif has no effect other than to be included in the 
count. 

Skipped instructions such as macro references are not expanded. Thus, 
any endif that would have resulted from an expansion is not detected. 

Skipping of a sequence initiated by an Ifeq. ifne or else that is assigned a 
name is terminated by an endif specifying the same name. Skipping of a 
sequence initiated by an unnamed ifeq. ifne or else is terminated by an 
unnamed endif. 
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4.6.2. ELSE - Reverse Effects of IF. 

else 

<lf-Pftme> 

An optional symbol; defines the name of an ifeq, ifne or else sequence; or 
blank. 

Description: 

By means of the else instruction the assembler provides the facility to 
Teverse the effects of an If test within the if range. An else detected during 
slapping causes assembly to resume at the instruction following the else. 
An else detected while a sequence is being assembled initiates skipping of 
source code following the else. Skipping continues until either an end or 
an for the sequence is detected. 

An else specifying the sequence by name terminates skipping of a sequence 
initiated by an Ifeq or ifne with the same name. An unnamed else ter¬ 
minates skipping of a sequence initiated by an u nn a m ed ifeq or ifne. 
Skipped instructions such as macro references are not expanded; any else 
that would have resulted from the expansion.is not detected. 

4.6.3. IFEQ - Test Expression Is Equal Zero. 

4.6.4. IFNE - Test Exp res sion is Not Equal Zero. 

name >} . ifeq <expression>i.<line.count>J 
J<if-name>j ifne <expression>|.<line-count>J 

<lf«name> , . * 

An optional symbol, defines the name of the ifeq or ifne sequence; or blank. 

<expression> 

A simple expression without forward reference. If the expression is errone¬ 
ous, an error message is printed and assembly continues with the next 
instruction. 

<line_count> 

Optional absolute value*specifying an integer count of the number of state¬ 
ments to be skipped. 

Description: , 

The ifeq and ifne pseudo instructions test the value of the expression and 

assemble instruction in the if range when the condition is satisfied. 

The <ine_count>, if specified, takes precedence over an <Lf-name>. if specified 

at all. 
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4.7. Source Stream Control 


4.7.1. INSERT - Insert Secondary Source. 

insert 

Description: 

The insert pseudo instruction provides a means of obtaining source state¬ 
ments from a file other than that being used for input. The assembler 
transfers the text from this hie and assembles it before string the next 
statement from the interrupted source of statements. 

There are no parameters for the insert pseudo instruction. The file to be used is 
specified when the assembler is called (see 6.) The file-will be rewound before 
using it. Under UNDC. the preprocessor cpp supports the inclusion of files and 
some other features, cpp may be used with the assembler (see 6.). Its usage is 
described in 

Kemighan B. W.; Ritchie D. K.: 

The C Programming Language. 

Prentice-Hall Software Series: Chapter 4.11 

4.8. listing Control 

The pseudo instructions described in this section permit extensive control of 
the assembly listing format. 


4.8.1. LIST-Listing 

list <opj>. <op 2 > .... <op a > 

<OPi> 

Optional parameter. A list option or a list option prefixed by a minus sign. 
The unprefixed option selects the option: the prefixed option cancels it. 
Options are separated by commas and terminated by a blank. The following 
options are available: 

dc When dc is selected, the source line of the dc pseudo Instruction and its 
expansion are listed, otherwise only the source line will be listed. 

-dc is the default. 

if When if is selected, the source lines of the Ifeq, ifne, else or endif pseudo 
instructions and the skipped source statements in the if range are listed, 
otherwise the pseudo instructions are listed, but not the skipped source 
statements. 

-if is the default. 

macro 

When macro is selected, the source line of the macro reference and the 
fully expanded macro body are listed, otherwise only the source line of the 
outermost macro reference of possibly nested macro calls is listed. 

-macro is the default. 
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3C0DC 

"When xopc is .‘selected, the assembler will list the use of all opcodes in the 
cross reference list. 

•xopc is the default. 

xpse 

1?hen xpse is selected, the assembler will list the use of all pseudo instruc¬ 
tion in the cross reference list. 

•xpse is the default. 


xreg 

"When xreg iskaelected. the assembler will list the use of all registers In the 
cross reference list. 

•xreg is the default. 


Description: 

The list pseudo instruction controls the content and format of the assem¬ 
bler listing. Use of the list pseudo instruction is optional. If not specified in 
a module, or if specified without parameters, the assembler will produce an 
output according to the default for each possible option. 


For compatibility with the Motorola assembler the pseudo instruction g is also 
accepted. 


Z 


Description:. 

The effect of the g pseudo instruction is 


Identical with the effect of 


list dc 


4.8 JL NOUST - Turn off listing 


nolist 

nol 


^ 6S The nolist pseudo instruction suppresses the printing of the assembly list¬ 
ing until a list pseudo instruction is encountered. 


4.8.3. PAGE - Top of Page, 
page 

Description: , . 

The page pseudo instruction advances printer paper to a new page before 
printing. Then page headings are printed and listing continues. The page 
pseudo instruction does not appear on the program listing. 


4.B.4. NOPAGE - Turn oil Paging. 


nopage 
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Description: ... . . 

The nopage pseudo instruction suppresses paging to the output 
Page and line numbers in the cross reference and error listing 
meaningless. 


device, 
•will be 


4 ft s SPC- Space Between Source Lines, 
spc <count> 

<count> 

An absolute value. 

Descr^iti n instruction causes the assembler to output <count> blank 

lines to the assembly listing. The spc pseudo instruction does not appear 
on the program listing. 


4.8.6. TTL - Assembly Listing Title. 

4.3.7. STTL - Assembly listing Subtitle. 


ttl *<text>’ 
sttl *<text>* 

ription: . . „ . .... 

The ttl and sttl pseudo instruction allow the progra mm er to print a title 
and a subtitle on the top of each page of the listing. To this effect the 
assembler maintains internally two text strings which are set to blank at 
the beg innin g of pass one. In pass two. whenever a new page is started, 
these two text strings together with other information are printed in the 
page header. Specifying a title or subtitle merely means, that the contents 
of the corresponding internal text string is changed to the one specified 
with the ttl or sttl pseudo instruction. It does not imply an automatic start 
of a new page. The first specified title is in addition kept in a third internal 
text string and is copied into the title text string at the start of pass two. 
Neither the ttl nor the sttl pseudo instruction are listed in the assembly 
listing. 


4 . 3 . 3 . FAIL - Cenerate an Error Message, 
fail 

Description: 

An error message is printed on the assembly listing. 


4.9. Object Code Control 

The pseudo instructions blong. bshort, flong or fshort allow the progr amm er to 
influence the assembler's choice whenever forward references or relative sym¬ 
bols are encountered, be it for direct addresses or relative branc hing instruc¬ 
tions. 
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4.9.1. BLONG - Use Two-Word Br un c h . 
4 . 9 2 .. BSHORT - Use One-Word Branch. 


blong 
b short 

cription: 

The two pseudo instructions blong end bshort allow the progra mme r to 
influence the assembler whenever it is asse mbl i ng a forward reference. By 
default the assembler will use the two-word instruction term allowing a 
larger relative address range. After a bshort pseudo instruction the assem¬ 
bler will generate the one-word relative branch instruction, unless the 
suffix i a blong pseudo instruction forces the two-word relative brancn 
instruction to be generated, unless the suffix .s has been appended to that 
branch instruction. 


4.9.3. FLONG - Force Direct Long Address. 

4.9.4. FSHORT - Force Direct Short Address. 

Hong 
f short 

^ The two pseudo instructions flong and fshort allow the progr am mer to 
influence the assembler whenever it is assembling an direct address the 
label of which contains a forward reference. By default the assembler will 
use the long direct address form. After an fshort pseudo instruction the 
assembler will generate the direct short address form. The occurrence of a 
fSnng pseudo instruction forces the direct long address form to be gen¬ 
erated. 


wr> The selected option, long or short direct addresses. Is only valid until the 
next occurrence of a llong. fshort or segment control pseudo instruction. 


4.9.5. NOOBJ - Suppress a.out Output. 


noobj 


Description: 

The pseudo ins truction, noobj suppresses the generation 


of a a.out module. 
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4.10. Cross Reference Control 

The pseudo instructions allow the programmer to select whether a cross refer¬ 
ence listing shall be built up and printed at the end of the assembler listing. De¬ 
fault is sref on. 

zrefon 

Description: 

A cross reference listing is built up and printed. 
zrefoH 
Description: 

A cross reference listing is suppressed. 
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5. MACRO OPERATIONS 

A macro definition is a sequence of source statements that ere saved and then 
assembled whenever needed through a macro call. A macro call consists of the 
occurrence of the macro name in the operation field of a statement. It usually 
includes parameters to be substituted for formal parameters in the macro code 
sequence so that code generated can vary with each assembly of the definition. 

* 

Use of a macro requires two steps, definition of the macro, and calling of the 
definition. 

A definition consists of three parts: heading, body, and terminator. 

heading A macro definition is headed by a macro pseudo instruction stating 
the p«rni» of the macro. The heading optionally includes a local 
pseudo instruction identifying symbols local to the definition. 

body The body begins with the first statement in a definition that is not a 

local pseudo instruction or a comment line. The body consists of a 
series of symbolic instructions. All instructions other than end or 
another macro definition are legal within a definition. The assem¬ 
bler recognizes substitutable arguments in all fields of the source 
line. The macro argument *0 however can only be used in the 
operation field for referring to the data size subparameter in an 
opcode or pseudo instruction. The arguments “1 through -9 can 
appear anywhere in' a source line. Ten is the maximum number of 
arguments that can be handled by any macro definition. Macro calls 
may be nested up to ten levels deep. 

terminator: An endm pseudo instruction terminates a macro definition. 


5.1. ENDM - fold Macro Definition, 
endm 

•An endm pseudo instruction terminates the macro definition. 


5 .2. LOCAL - Local Symbols. 

local .<symj>. <sjm ^>.... <sym a > 

<sym 1 > 

List of local symbols. Symbols must be separated by co mm as. A blank ter¬ 
minates the list. The maximum number of local symbols is 10. 

Description: 

The local pseudo instruction, which lists symbols local to the definition 
optionally follows the macro pseudo instruction. 

A symbol in the list is considered local to the macro; that is, it is known only 
within the macro definition. On each expansion of the macro, the assembler 
creates a new symbol for each local symbol and substitutes it for each 
occurrence of the local symbol in the definition. Thus invented symbols replace 
local named symbols wherever they appear in a macro definition in a mann er 
similar to the way substitutable parameters are replaced. 




5.3. HACKO - Macro Heading. 
<m—name> macro 
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<m_aarae> 

A mandatory symbol that defines the name of the macro. 

Description: 

A macro pseudo instruction tells the assembler to place the Instructions 
forming the body of the macro in a table of macro definitions for assembly 
upon call, and to place the macro name in the symbol table. 


5.4. MACRO CALLS 


A macro headed by a macro pseudo instruction can be called by an instruction 
in the following format: 


<symbol> 

<symbol> 

<symbol> 

<symbol> 

<symbol> 

<symbol> 


<m_name>a 

<m_name>.b 

<m_name>.w 

<nuiame>l 


An optional location symboL 


<Pj>. 

<?!>• 

<?!>• 

<*>:>. 

<?>!>. 


^Pg^ .... 

<P2^ .... 
^ 2 ^ 


<m_name> 

Name of a previously defined macro. The (optional) size attribute substi¬ 
tutes macro parameter 0 (see above). 


<Pi> 

Para m eter list composed of strings of characters. Parameters are 
separated by commas and terminated by a blank. Two consecutive commas 
constitute a null parameter. 

If null parameters are interspersed with non-null parameters, the correct posi¬ 
tions must be established with commas. When the list terminates before the last 
possible parameter, all remaining parameters are considered null. 


When the first character of a parameter is a left angle bracket ( < ), the assem¬ 
bler considers all the characters between it and the matching right angular 
bracket ( > ) as one parameter. The assembler removes the outer pair of angle 
brackets before substituting the enclosed character string in a line. Embedded 
brackets must be properly paired. A bracketed item can contain blanks and 
commas. 
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6. HOW TO USE THE ASSEMBLER 

The assembler has been designed as a two pass assembler and is written in Pas¬ 
cal. To run the assembler two input files (INPUT - assembler source. INSERT - 
accessed only by the insert pseudo instruction), two output files (OUTPUT - 
as sembl er listing. AOUT - a.out object module) and two work files (^CRATCH. 
XREJTTL) must be provided. 

Under UNIX the shell procedure os runs the preprocessor cpp and the assembler 
asm. One or more assembler sour ce file s may be listed as arguments. There is 
no provision for assignment of INSERT since insertion can be achieved more 
conveniently by use of cpp. Following UNIX convention. AOUT is written on a file 
named <aame>.o. while the assembler sources should be named Ciameb.s. list¬ 
ings will be displayed to <name>.lst. 


<source>.s 

(assembler + cpp instructions) 



<source>.o <source>Jst 

Example 1: 

as myso urce.s . 
reads mysource.s 

displays- the listing to mysource-lst, the object module to mysource.o 

Example 2: 

as mysource*.s 

reads mysourceO.s mysourcel.s mysource3.s 

files the listings to mysourceO.lst mysourcel.lst mysource3.1st 

writes the object modules to mysourceO.o mysourcel.o mysource3.o 


Should you experience any problems or encounter errors, please contact the 
author. 


J 






- 23- 


7. APPENDIX 

Symbols and related address modes and relocation Information 


symbol type 

textsegment 

datasegment 

absolute 

DA (r-abs) 

DA (r-abs) 

text 

PCD16 (r-abs) 

DA (rJtext) 

DA (r-iext) 

data 

DA (r-data) 

PCD16 (r-abs) 

DA (rJtext) 

bss 

DA (r-bss) 

DA (r-bss) 

external 

DA (r-ext) 

DA (r-ext) 


Notation: 

DA direct addressing mode 

PCD16 program counter relative addressing mode (generated if requested) 

Belated relocation information . • 

r-abs • (absolute symbol) 
r-text (text symbol) 
r-data (data symbol) 
r-bss (bss symbol) 
r-ext (external symbol) 
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List of Error Messages 


Oxonstant too large 

^character not defined for m 68000 assembler 

2:character missing or not valid for constant 

3:string too long or not terminated properly 

4:entry point or external symbol multiply defined 

5:entry point not defined 

?:$ymbol cannot be used as a label 

8:this operation needs a label 

S:this operation does not allow a label 

I0:symbol multiply defined 

12:symbol not defined 

13:initial ifeq or lfne is missing or misplaced 
14rthe label of an if should not be used here 
15:if conditions more than maxi nest levels deep 
18:symbol cannot be used as an opcode 
17:size specification illegal or not allowed 
18:macro expansion error 
19:more.than maxmlocal local parameters 
20:at most one local pseudo per macrodefinition 
21:initial macro definition missing or misplaced 
22:macro calls more than maxmnest levels deep 
23:> expected 

24:do not nest macro definitions 

2S:opcode/macro or pseudocode missing 

26:no such cross-reference option 

28:operation needs one or more operands 

29:address or data register expected 

30:address register ejected 

31:bad termination of an expression 

32:an expression cannot start with this symbol 

33:an operand cannot start with this symbol 

34:the count must be absolute for this pseudo 

35:the count must be positive for this pseudo 

36:the expression must be greater lc for org pseudo 

38:displacements are restricted to byte or word size 

40:argument(s) missing in expression 

41:displacement is restricted to byte size 

42:type conflict between address and program counter 

43:expression too complicated, use equ or set pseudo to break it down 

44:expression too large for size specified 

45 :forward reference not allowed for this pseudo 

46:both arguments must be absolute for logical operations 

47 : j option does not allow branch to next word 

48:register specification expected 

49:) expected 

50:) or. expected 

51:separator expected 

52:no size specification for this operation 

53:byte size specification not allowed 

54 :both arguments must be absolute for shift operations 

55:string expected 
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Iist of Error Messages (continued) 

56:too many operands are specified for this operation 
57 :both arguments must be absolute for * or / 

58:this address mode is Illegal for the opcode 
59 :address mode combination illegal for opcode 
60:do not -write a comment on this line 
6 ^synchronization error between pass one and two 
62:too many errors this instruction line 
63:fail generated error, consult listing 
64:syntax error in register list for modern 
85:org argument is of illegal type 
68 :no code generation in bss segment 
69:list options are: dc. if. macro, xopc, xpse. xreg 
70:one argument must be absolute for add operation 
71:illegal operand types for sub operation 
72:a.out buffers exceeded 


✓ 






Erganzungen zu II UNIX - Fortran 77 


v» '. 


Norbert BLa.it 
PCS Gmbh 

Pfalzer- Wald- Strasse 36 
6000 Afunchen 90 


1. Einleitung 

An dieser Stelle werden verschiedene systemspezifische Eigenschaften des 
MUNIX Fortran-77 Systems beschrieben, die in [1] nicht dargestellt werden. 


2. Hinweise zu einigen Statements 
2.1 OPEN-statement 

- Nach einem QPETVsteht der "file-pointer" iramer auf end-of-file. 
Soil von einem sequentiellen File gelesen werden, so muss 
daher nach dem OPEN ein REWIND -statement ausgefuhrt werden. 


Der Filename muss, wenn er nicht als Literal angegeben wird, 
als CHARACTER *N deVXaTierl sein. 


- Bei direct-access-Files muss die Recordlange in Byte angegeben 
werden. 


- Bei status= 'new'dart, im Gegensatz zu friiheren Versionen, 
das angegebene File nicht existieren, bei status^ 'old 'muss 
es dagegen vorhanden sein. 








2.2 READ/WHITE-statements 

- Entgegen der friiheren Darstellung in [l] konnen die Fileunits 
0-18 verwendet werden. Devon sind vorbelegt: 

0 - stderr (standard error output) = Terminal. Die Ausgabe kann 
durch "2>errors'' in der Kommandozeile auf ein 
File "errors" umgeleitet werden. 

5 - stdin (standard input) = Terminal. Die Eingabe kann durch 

"<input" in der Kommandozeile von einem File 
"input" erfolgen. 

6 - stdout (standard output) = Terminal. Die Ausgabe kann 

durch ">output" in der Kommandozeile auf ein 
File "output" umgeleitet werden. 


- Interne Files (entspricht ENCODE/DECODE auf anderen Systemen) 
miissen 

a) bei nur einem Record der Lange N als 

CHARACTER*N record 

b) bei m Records (m > 1) der Lange N als 

CHARACTER*N record(m) 
deklariert werden. 


Eine geklammerte E/A-Liste ohne implizite DO-Schleife ist ein 
Syntax-Fehler (ist in Standard Fortran-77 nicht erlaubt). 


Ein CHARACTER-Yi ert, der listengesteuert ausgegeben wurde, 
kann nicht wieder eingelesen werden (It. Standard Fortran-77 
werden CHARACTER als ein Zeichen ausgegeben. aber nur geklam- 
mert in ’ oder " eingelesen !). 




* 




2.3 DATA-slateinent 

- In DATA-Anweisungen konnen fiir CHARACTER nur darstellbare 
ASCII-Zeichen oder Ersatzzeichen verwendet werden. 

Ersatzzeichen : \0 (binar Null), 

\f (formfeed), 

\n (newline),... 

W (\) 

siehe auch in [l] Punkt 2.9. 

Eine Oktal- oder Hexadezimal-Darstellung wie bei INTEGER-Werten 

ist nicht moglich, ist aber fiir spatere Versionen 

vorgesehen. 


2.4 PARAMETER-statement 

- Im Gegensatz zu ZJATA-Anweisungen besteht bei der PARAMETER -Anweisung 
durchaus die Moglichkeit, CHARACTER-Konstanlen nicht darstellbare 
ASCII-Zeichen zuzuordnen. 

Beispiel : 

PARAMETER (ETX = char(3)) 

Durch diese Anweisung wird eine CHARACTER-Konstante ETX definiert, 
die den binaren Wert 3 erhalt. 


3. Allgemeine Hinweise 

3.1 COMMON-Blocke 

- COMMON-Blocke durfen nur langer als 32 kByte sein, 
falls man beim Ubersetzen die Option -D verwendet. 

- COMMON-Blocke miissen bei jeder Deklaration die gleiche 
Lange besitzen ! 

3.2 Feld-Deklarationen 

- Felder durfen nur langer als 32 kByte sein, wenn man 
beim Ubersetzen die Option -D verwendet. 




« 


A. 









3.3 Sonstiges 

- Konversionen zwischen den Datentypen 

CHARACTER-Werte —> INTEGER-Werte : Konversion automatisch 
INTEGER-Werte — > CHARACTER-Werte : char-Function (intrinsic) 

INTEGER*2-Werte — > INTEGER*4-Werte : int4-Function 
INTEGERM-Werte — > INTEGER*2-Werte : int2-Function 

- Die UNIX-spezifische Verwendung des Zeichens "\" als Fluchtsymbol 
bedingt auch in Fortran-77 eine abweichende Handhabung dieses 
Zeichens. Anstelle eines "\" sind stets zwei ("\ V f ) anzugeben. 

Dazu siehe auch in [l] Punkt 2.9 und Punkt 2.3 oben. 


- EQUIVALENCE auf CHARACTER-Feldern durfen nur bei ungeraden 
Indices beginnen, sonst kommt es zu Laufzeitfehlem 
(odd address error). 


- Die Fortran-Steuerzeichen 1,0,+ und (space) werden bei der 
Ausgabe nicht interpretiert. Sie konnen jedoch mit dem 
Filter "fpr" (siehe Man. 1) auf dem Drucker oder dem Terminal 
ausgegeben werden. 


Die (Unter-) Programme die einen Aufruf der Funktion inquire 
enthalten, miissen bei einer Umstellung von MUNIX-Version 1.4/06 
auf MUNIX-Version 1.5 neu ubersetzt werden. 


Zum Laden von bereits iibersetzten f77-Moduln (suffix : .o) 
sollte wie beim Compilieren der Aufruf 
#, f77 prog.o sub.o ..." 

verwendet werden. Damit werden dann automatisch alle notwendigen 
Bibliotheken dazu gebunden und ein lauffahiges Programm erstellt. 


Ab MUNIX-Version 1.5 hat sich die Bedeutung der f77-0ption -14 
verandert. 

Ohne Verwendung weiterer Optionen bedeutete -14 
fruher : 4-Byte Integer , 4-Byte Indices 
jetzt : 4-Byte Integer, 2-Byte Indices. 

Dies bedeutet, dass man statt wie fruher -14 nun -D 
verwenden muss. 


4 . Abschliessende Bemerkungen 

Ich hoffe, dass Ihnen mit diesen Hinweisen die Arbeit mit dem 
CADMUS/MUNIX-Fortran-77 Compiler und Laufzeitsystem erleichtert 
wird. Hinweise Ihrerseits werden vom Autor gerne entgegengenommen. 




* 






Literatur: 


[l] - S.I. Feldman, P.J. Weinberger, 

A Portable Fortran 77 Compiler, 

Bell Lab’s Murray Hill, New Jersey 07974 
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Unsolved Problems 

There are several unsolved problems in the fortran-77 runtime-system. 

1. statement-functions 

Using the archaic feature of statement-functions in fortran-77 
errors can occur. To avoid such errors, use normal functions 
instead. 


2. DATA-statement 

The error-message overlapping initialisation without 
any linenumber can occur during initialisation of 
CHARA CT£7?-strings. 


3. The option -fN 

Using the -fN option the error-message out of registers 
means that you have to simplify your arithmetic expressions. 


Restrictions 

assign- statement 

A /’OtfA/AT’-statement must be given before an assign-statement 
that assigns the label of the format statement to an integer variable. 
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Changes in f77 (MUNIX-Version 1.4/06 to 1.5) 

There are several changes in the f77 runtime-system. 

These are : 

1. the inquire-function. 

The internal call of the inquire-function has changed, 
i. e. you have to compile at least the (sub-)programs 
which call this function. 

2. the option -14. 

Without any other options it means now only 4-byte-integer 
(not as earlier also 4-byte-subscipts). 

To run with 4-byte-subscipts you now have to choose the 
-II (ell) option, i.e. you have to change your invocation 
of the f77-compiler e.g. from 

f77 -14 prog.f 

into 

f77 -D prog.f 

3. the open-statement. 

The meaning of the argument "status” has been changed 
according to the standard definition of Fortran-77. 

If status=’new* is given, the file must not exist, if 
status=‘old' is given the file must exist. Otherwise 
an error is reported. 



t. 
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ABSTRACT 

The Fortran language has just been revised. The new language, 
known as Fortran 77, became an official American National Stan¬ 
dard on April 3. 1978. We report here on a compiler and run¬ 
time system for the new extended language. This is believed to 
be the first complete Fortran 77 system to be implemented. This 
compiler is designed to be portable, to be correct and complete, 
and to generate code compatible with calling sequences pro¬ 
duced by C compilers. In particular, this Fortran is quite usable 
on UNKt systems. In this paper, we describe the language com¬ 
piled, interfaces between procedures, and file formats assumed 
by the I/O system. An appendix describes the Fortran 77 
language. 


1 August 1978 


tUNDC is • Trademark of Bell Laboratories. 






A Portable Fortran 77 Compiler 

S. I. Feldman 

P. J. Weinberger 

Bell Laboratories 
Murray Hill, New Jersey 07974 


1. INTRODUCTION 

The Fortran language has just been revised. The new language, known as 
Fortran 77, became an official American National Standard [1] on April 3, 
1978. for the language, known as Fortran 77, is about to be published. For¬ 
tran 77 supplants 1966 Standard Fortran [2]. We report here on a compiler 
and run-time system for the new extended language. The compiler and com¬ 
putation library were written by SIF, the I/O system by PJW. We believe ours 
to be the first complete Fortran 77 system to be implemented. This compiler 
is designed to be portable to a number of different machines, to be correct 
and complete, and to generate code compatible with calling sequences pro¬ 
duced by compilers for the C language [3]. In particular, it is in use on UNIXf 
systems. Two families of C compilers are in use at Bell Laboratories, those 
based on D. M. Ritchie’s PDP-11 compiler[4] and those based on S. C. 
Johnson's portable C compiler [5]. This Fortran compiler can drive the 
second passes of either family. In this paper, we describe the language com¬ 
piled, interfaces between procedures, and file formats assumed by the I/O 
system. We will describe implementation details in companion papers. 

1.1. Usage 

At present, versions of the compiler run on and compile for the PDP-11, 
the VAX-11 /780, and CADMUS 9000 UNIX systems. For the command to run the 
compiler see f77(l). 

1.2. Documentation Conventions 

In running text, we write Fortran keywords and other literal strings in 
boldface lower case. Examples will be presented in lightface lower case. 
Names representing a class of values will be printed in italics. 

1.3. Implementation Strategy 

The compiler and library are written entirely in C. The compiler gen¬ 
erates C compiler intermediate code. Since there are C compilers running on 
a variety of machines, relatively small changes will make this Fortran com¬ 
piler generate code for any of them. Furthermore, this approach guarantees 
that the resulting programs are compatible with C usage. The runtime com¬ 
putational library is complete. The mathematical functions are computed to 
at least 63 bit precision. The runtime I/O library makes use of D. M. Ritchie’s 
Standard C I/O package [8] for transferring data. With the few exceptions 
described below, only documented calls are used, so it should be relatively 
easy to modify to run on other operating systems. 


tUNIX is a Trademark of Bell Laboratories. 
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2. LANGUAGE EXTENSIONS 

Fortran 77 includes almost all of Fortran 66 as a subset. We describe the 
differences briefly in the Appendix. The most important additions are a char¬ 
acter string data type, file-oriented input/output statements, and random 
access I/O. Also, the language has been cleaned up considerably. 

In addition to implementing the language specified in the new Standard, 
our compiler implements a few extensions described in this section. Most are 
useful additions to the language. The remainder are extensions to make it 
easier to communicate with C procedures or to permit compilation of old 
(1966 Standard) programs. 

2.1. Double Complex Data Type 

The new type double complex is defined. Each datum is represented by a 
pair of double precision real variables. A double complex version of 
every complex built-in function is provided. The specific function names 
begin with z instead of c. 

2.2. Internal Files 

The Fortran 77 standard introduces "internal files” (memory arrays) and 
restricts their use to formatted sequential I/O statements. 

2.3. Implicit Undefined statement 

Fortran 66 has a fixed rule that the type of a variable that does not 
appear in a type statement is integer if its first letter is i, j. k, 1, m or n. 
and real otherwise. Fortran 77 has an implicit statement for overriding 
this rule. As an aid to good programming practice, we permit an addi¬ 
tional type, undefined. The statement 

implicit undefined(a-z) 

turns off the automatic data typing mechanism, and the compiler will 
issue a diagnostic for each variable that is used but does not appear in a 
type statement. Specifying the -u compiler flag is equivalent to begin¬ 
ning each procedure with this statement. 

2.4. Recursion 

Procedures may call themselves, directly or through a chain of other 
procedures. 

2.5. Automatic Storage 

Two new keywords are recognized, static and automatic. These keywords 
may appear as "types” in type statements and in implicit statements. 
Local variables are static by default; there is exactly one copy of the 
datum, and its value is retained between calls. There is one copy of each 
variable declared automatic for each invocation of the procedure. 
Automatic variables may not appear in equivalence, data, or save state¬ 
ments. 

2.6. Source Input Format 

The Standard expects input to the compiler to be in 72 column format: 
except in comment lines, the first five characters are the statement 
number, the next is the continuation character, and the next sixty-six 
are the body of the line. (If there ore fewer than seventy-two characters 
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on a line, the compiler pads it with blanks; characters after the seventy- 
second are ignored). 

In order to make it easier to type Fortran programs, our compiler also 
accepts input in variable length lines. An ampersand ("A”) in the first 
position of a line indicates a continuation line; the remaining characters 
form the body of the line. A tab character in one of the first six positions 
of a line signals the end of the statement number and continuation part 
of the line; the remaining characters form the body of the line. A tab 
elsewhere on the line is treated as another kind of blank by the compiler. 

In the Standard, there are only 26 letters — Fortran is a one-case 
language. Consistent with ordinary UNIX system usage, our compiler 
expects lower case input. By default, the compiler converts all upper 
case characters to lower case except those inside character constants. 
However, if the —U compiler flag is specified, upper case letters are not 
transformed. In this mode, it is possible to specify external names with 
upper case letters in them, and to have distinct variables differing only 
in case. Regardless of the setting of the flag, keywords will only be 
recognized in lower case. 

2.7. Include Statement 
The statement 

include 'stuff' 

is replaced by the contents of the file stuff, includes may be nested to a 
reasonable depth, currently ten. 

2.8. Binary Initialization Constants 

A logical, real, or integer variable may be initialized in a data statement 
by a binary constant, denoted by a letter followed by a quoted string. If 
the letter is b, the string is binary, and only zeroes and ones are permit¬ 
ted. If the letter is o, the string is octal, with digits 0—7. If the letter is z 
or x, the string is hexadecimal, with digits 0-9, a-f. Thus, the state¬ 
ments 

integer a(3) 

data a / b'1010', o'12’, z'a' / 
initialize all three elements of a to ten. 

2.9. Character Strings 

For compatibility with C usage, the following backslash escapes are 
recognized: 

\n newline 
\t tab 
\b backspace 
\f formfeed 
\0 null 

V apostrophe (does not terminate a string) 

V quotation mark (does not terminate a string) 

\\ \ 

\x x, where x is any other character 

Fortran 77 only has one quoting character, the apostrophe. Our com¬ 
piler and 1/0 system recognize both the apostrophe ( * ) and the double- 
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quote ( " ). If a string begins with one variety of quote mark, the other 
may be embedded within it without using the repeated quote or 
backslash escapes. 

Every unequivalenced scalar local character variable and every charac¬ 
ter string constant is aligned on an integer word boundary. Each char¬ 
acter string constant appearing outside a data statement is followed by a 
null character to ease communication with C routines. 

2.10. Hollerith 

Fortran 77 does not have the old Hollerith (nh) notation, though the new 
Standard recommends implementing the old Hollerith feature in order to 
improve compatibility with old programs. In our compiler, Hollerith data 
may be used in place of character string constants, and may also be used 
to initialize non-character variables in data statements. 

2.11. Equivalence Statements 

As a very special and peculiar case, Fortran 66 permits an element of a 
multiply-dimensioned array to be represented by a singly-subscripted 
reference in equivalence statements. Fortran 77 does not permit this 
usage, since subscript lower bounds may now be different from 1. Our 
compiler permits single subscripts in equivalence statements, under the 
interpretation that all missing subscripts are equal to 1. A warning mes¬ 
sage is printed for each such incomplete subscript. 

2.12. One-Trip DO Loops 

The Fortran 77 Standard requires that the range of a do loop not be per¬ 
formed if the initial value is already past the limit value, as in 

do 10 i = 2, 1 

The 1966 Standard stated that the effect of such a statement was 
undefined, but it was common practice that the range of a do loop would 
be performed at least once. In order to accommodate old programs, 
though they were in violation of the 1966 Standard, the —onetrip com¬ 
piler flag causes non-standard loops to be generated. 

2.13. Commas in Formatted Input 

The I/O system attempts to be more lenient than the Standard when it 
seems worthwhile. When doing a formatted read of non-character vari¬ 
ables, commas may be used as value separators in the input record, 
overriding the field lengths given in the format statement. Thus, the for¬ 
mat 

(ilO, f20.10, i4) 
will read the record 
—345,.05e—3,12 
correctly. 

2.14. Short Integers 

On machines that support halfword integers, the compiler accepts 
declarations of type integer*2. (Ordinary integers follow the Fortran 
rules about occupying the same space as a REAL variable; they are 
assumed to be of C type long int; halfword integers are of C type short 
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int.) An expression involving only objects of type integer*2 is of that 
type. Generic functions return short or long integers depending on the 
actual types of their arguments. If a procedure is compiled using the -12 
flag, all small integer constants will be of type integer*2. If the precision 
of an integer-valued intrinsic function is not determined by the generic 
function rules, one will be chosen that returns the prevailing length 
(integer*2 when the -12 command flag is in effect). When the -12 option 
is in effect, all quantities of type logical will be short. Note that these 
short integer and logical quantities do not obey the standard rules for 
storage association. 

2.15. Additional Intrinsic Functions 

This compiler supports all of the intrinsic functions specified in the For¬ 
tran 77 Standard. In addition, there are functions for performing bitwise 
Boolean operations ( or, and, xor, and not) and for accessing the UNIX 
command arguments ( getarg and iargc ). 

3. VIOLATIONS OF THE STANDARD 

We know only thre ways in which our Fortran system violates the new 

standard: 

3.1. Double Precision Alignment 

The Fortran standards (both 1966 and 1977) permit common or 
equivalence statements to force a double precision quantity onto an odd 
word boundary, as in the following example: 

real a(4) 

double precision b.c 
equivalence (a(l),b), (a(4),c) 

Some machines (e.g., Honeywell 6000, IBM 360) require that double preci¬ 
sion quantities be on double word boundaries; other machines (e.g., IBM 
370), run inefficiently if this alignment rule is not observed. It is possible 
to tell which equivalenced and common variables suffer from a forced 
odd alignment, but every double precision argument would have to be 
assumed on a bad boundary. To load such a quantity on some machines, 
it would be necessary to use separate operations to move the upper and 
lower halves into the halves of an aligned temporary, then to load that 
double precision temporary; the reverse would be needed to store a 
result. We have chosen to require that all double precision real and com¬ 
plex quantities fall on even word boundaries on machines with 
corresponding hardware requirements, and to issue a diagnostic if the 
source code demands a violation of the rule. 

3.2. Dummy Procedure Arguments 

If any argument of a procedure is of type character, all dummy pro¬ 
cedure arguments of that procedure must be declared in an external 
statement. This requirement arises as a subtle corollary of the way we 
represent character string arguments and of the one-pass nature of the 
compiler. A warning is printed if a dummy procedure is not declared 
external. Code is correct if there are no character arguments. 
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3.3. T and TL Formats 

The implementation of the t (absolute tab) and tl (leftward tab) format 
codes is defective. These codes allow rereading or rewriting part of the 
record which has already been processed. (Section 6.3.2 in the Appen¬ 
dix.) The implementation uses seeks, so if the unit is not one which 
allows seeks, such as a terminal, the program is in error. (People who 
can make a case for using tl should let us know.) A benefit of the imple¬ 
mentation chosen is that there is no upper limit on the length of a 
record, nor is it necessary to predeclare any record lengths except 
where specifically required by Fortran or the operating system. 


4. INTER-PROCEDURE INTERFACE 

To be able to write C procedures that call or are called by Fortran pro¬ 
cedures. it is necessary to know the conventions for procedure names, data 
representation, return values, and argument lists that the compiled code 
obeys. 

4.1. Procedure Names 

On UNIX systems, the name of a common block or a Fortran procedure 
has an underscore appended to it by the compiler to distinguish it from a C 
procedure or external variable with the same user-assigned name. Fortran 
library procedure names have embedded underscores to avoid clashes with 
user-assigned subroutine names. 


4.2. Data Representations 

The following is a table of corresponding Fortran and C declarations: 
Fortran C 


integer*2 x 
integer x 
logical x 
real x 

double precision x 
complex x 
double complex x 
characters x 


short int x; 
long int x; 
long int x; 
float x; 
double x; 

struct { float r, i; J x; 
struct ( double dr, di; J x; 
char x[6]; 


(By the rules of Fortran, integer, logical, and real data occupy the same 
amount of memory). 


4.3. Return Values 


A function of type integer, logical, real, or double precision declared as a 
C function that returns the corresponding type. A complex or double com¬ 
plex function is equivalent to a C routine with an additional initial argument 
that points to the place where the return value is to be stored. Thus. 


complex function f( . .. ) 

is equivalent to 

f__(temp,*.. .) 

struct | float r, i; J ♦temp; 


A character-valued function is equivalent to a C routine with two extra initial 
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arguments: a data address and a length. Thus, 

character*15 function g( ... ) 

is equivalent to 

g_(result, length, .. .) 
char result[ ]; 
long int length; 

and could be invoked in C by 
char chars[l5]; 

g_(chars, 15L,.. .); 

Subroutines are invoked as if they were integer^valued functions whose value 
specifies which alternate return to use. Alternate return arguments (state¬ 
ment labels) are not passed to the function, but are used to do an indexed 
branch in the calling procedure. (If the subroutine has no entry points with 
alternate return arguments, the returned value is undefined.) The statement 

call nret(*l, *2, *3) 

is treated exactly as if it were the computed goto 
goto (1,2, 3), nret() 

4.4. Argument lists 

All Fortran arguments are passed by address. In addition, for every 
argument that is of type character or that is a dummy procedure, an argu¬ 
ment giving the length of the value is passed. (The string lengths are long int 
quantities passed by value). The order of arguments is then: 

Extra arguments for complex and character functions 
Address for each datum or function 
A long int for each character or procedure argument 

Thus, the call in 

external f 
character*? s 
integer b(3) 

call sam(f, b(2), s) 

is equivalent to that in 

int f(); 
char s[7); 
long int b[3]; 

sam__(f, &b[l], s, OL, 7L); 

Note that the first element of a C array always has subscript zero, but For¬ 
tran arrays begin at 1 by default. Fortran arrays are stored in column-major 
order, C arrays are stored in row-major order. 
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5. FILE FORMATS 

5.1. Structure of Fortran Files 

Fortran requires four kinds of external files: sequential formatted and 
unformatted, and direct formatted and unformatted. On UNIX systems, these 
are all implemented as ordinary files which are assumed to have the proper 
internal structure. 

Fortran 1/0 is based on "records''. When a direct file is opened in a For¬ 
tran program, the record length of the records must be given, and this is 
used by the Fortran I/O system to make the file look as if it is made up of 
records of the given length. In the special case that the record length is 
given as 1, the files are not considered to be divided into records, but are 
treated as byte-addressable byte strings; that is, as ordinary UNIX file system 
files. (A read or write request on such a file keeps consuming bytes until 
satisfied, rather than being restricted to a single record.) 

The peculiar requirements on sequential unformatted files make it 
unlikely that they will ever be read or written by any means except Fortran 
1/0 statements. Each record is preceded and followed by an integer contain¬ 
ing the record's length in bytes. 

The Fortran I/O system breaks sequential formatted files into records 
while reading by using each newline as a record separator. The result of 
reading off the end of a record is undefined according to the Standard. The 
I/O system is permissive and treats the record as being extended by blanks. 
On output, the 1/0 system will write a newline at the end of each record. It is 
also possible for programs to write newlines for themselves. This is an error, 
but the only effect will be that the single record the user thought he wrote 
will be treated as more than one record when being read or backspaced over. 

5.2. Portability Considerations 

The Fortran I/O system uses only the facilities of the standard C I/O 
library, a widely available and fairly portable package, with the following two 
nonstandard features: The I/O system needs to know whether a file can be 
used for direct I/O, and whether or not it is possible to backspace. Both of 
these facilities are implemented using the fseek routine, so there is a routine 
canscek which determines if fseek will have the desired effect. Also, the 
inquire statement provides the user with the ability to find out if two files are 
the same, and to get the name of an already opened file in a form which would 
enable the program to reopen it. (The UNIX operating system implementation 
attempts to determine the full pathname.) Therefore there are two routines 
which depend on facilities of the operating system to provide these two ser¬ 
vices. In any case, the I/O system runs on the PDP-11, VAX-11/780, and 
Interdata 8/32 UNIX systems. 

5.3. Pre-Connected Files and File Positions 

Units 5. 6. and 0 are preconnected when the program starts. Unit 5 is 
connected to the standard input, unit 6 is connected to the standard output, 
and unit 0 is connected to the standard error unit. All are connected for 
sequential formatted I/O. 

All the other units are also preconnected when execution begins. Unit n 
is connected to a file named fort.n. These files need not exist, nor will they be 
created unless their units are used without first executing an open. The 
default connection is for sequential formatted I/O. 
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The Standard does not specify where a file which has been explicitly 
opened for sequential 1/0 is initially positioned. In fact, the I/O system 
attempts to position the file at the end, so a write will append to the file and a 
read will result in an end-of-file indication. To position a file to its beginning, 
use a rewind statement. The preconnected units 0, 5, and 6 are positioned as 
they come from the program’s parent process. 
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APPENDDC Differences Between Fortran 66 and Fortran 77 

The following is a very brief description of the differences between the 
1966 [2] and the 1977 [l] Standard languages. We assume that the reader is 
familiar with Fortran 66. We do not pretend to be complete, precise, or 
unbiased, but plan to describe what we feel are the most important aspects of 
the new language. At present the only current information on the 1977 Stan¬ 
dard is in publications of the X3J3 Subcommittee of the American National 
Standards Institute. The following information is from the ,, /92” document. 
This draft Standard is written in English rather than a meta-language, but it 
is forbidding and legalistic. No tutorials or textbooks are available yet. 

1. Features Deleted from Fortran 66 

1.1. Hollerith 

All notions of ’•Hollerith’* (nh) as data have been officially removed, 
although our compiler, like almost all in the foreseeable future, will con¬ 
tinue to support this archaism. 

1.2. Extended Range 

In Fortran 66, under a set of very restrictive and rarely-understood con¬ 
ditions, it is permissible to jump out of the range of a do loop, then jump 
back into it. Extended range has been removed in the Fortran 77 
language. The restrictions are so special, and the implementation of 
extended range is so unreliable in many compilers, that this change 
really counts as no loss. 

2. Program Form 

2.1. Blank lines 

Completely blank lines are now legal comment lines. 

2.2. Program and Block Data Statements 

A main program may now begin with a statement that gives that program 
an external name: 

program work 

Block data procedures may also have names, 
block data stuff 

There is now a rule that only one unnamed block data procedure may 
appear in a program. (This rule is not enforced by our system.) The 
Standard does not specify the effect of the program and block data 
names, but they are clearly intended to aid conventional loaders. 

2.3. ENTRY Statement 

Multiple entry points are now legal. Subroutine and function subpro¬ 
grams may have additional entry points, declared by an entry statement 
with an optional argument list. 

entry extra(a, b. c) 

Execution begins at the first statement following the entry line. All vari¬ 
able declarations must precede all executable statements in the pro¬ 
cedure. If the procedure begins with a subroutine statement, all entry. 
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points ere subroutine names. If it begins with a function statement, 
each entry is a function entry point, with type determined by the type 
declared for the entry name. If any entry is a character-valued function, 
then all entries must be. In a function, an entry name of the same type 
as that where control entered must be assigned a value. Arguments do 
not retain their values between calls. (The ancient trick of calling one 
entry point with a large number of arguments to cause the procedure to 
•’remember” the locations of those arguments, then invoking an entry 
with just a few arguments for later calculation, is still illegal. Further¬ 
more, the trick doesn't work in our implementation, since arguments are 
not kept in static storage.) 

2.4. DO Loops 

do variables and range parameters may now be of integer, real, or double 
precision types. (The use of floating point do variables is very dangerous 
because of the possibility of unexpected roundoff, and we strongly 
recommend against their use). The action of the do statement is now 
defined for all values of the do parameters. The statement 

do 10 i = 1, u, d 

performs max(o,l(u-f)/dJ) iterations. The do variable has a predictable 
value when exiting a loop: the value at the time a goto or return ter¬ 
minates the loop; otherwise the value that failed the limit test. 

2.5. Alternate Returns 

In a subroutine or subroutine entry statement, some of the arguments 
may be noted by an asterisk, as in 

subroutine s(a, ♦, b, •) 

The meaning of the "alternate returns” is described in section 5.2 of the 
Appendix. 

3. Declarations 

3.1. CHARACTER Data Type 

One of the biggest improvements to the language is the addition of a 
character-string data type. Local and common character variables must 
have a length denoted by a constant expression: 

character*17 a, b(3,4) 
character*(6+3) c 

If the length is omitted entirely, it is assumed equal to 1. A character 
string argument may have a constant length, or the length may be 
declared to be the same as that of the corresponding actual argument at 
run time by a statement like 

character*(*) a 

(There is an intrinsic function len that returns the actual length of a 
character string). Character arrays and common blocks containing 
character variables must be packed: in an array of character variables, 
the first character of one element must follow the last character of the 
preceding element, without holes. 
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3.2. IMPLICIT Statement 

The traditional implied declaration rules still hold: a variable whose 
name begins with i. j. k, 1, in, or n is of type integer, other variables are of 
type real, unless otherwise declared. This general rule may be overrid¬ 
den with an implicit statement: 

implicit real(a-c.g), complex(w-z), character^ 17) (s) 

declares that variables whose name begins with an a ,b. c, or g are real, 
those beginning with w, x. y, or z are assumed complex, and so on. It is 
still poor practice to depend on implicit typing, but this statement is an 
industry standard. 

3.3. PARAMETER Statement 

It is now possible to give a constant a symbolic name, as in 

parameter (x=17, y=x/3, pi=3.14159d0, s='hello') 

The type of each parameter name is governed by the type of the con¬ 
stant expressions. The right side of each equal sign must be a constant 
expression (an expression made up of constants, operators, and already 
defined parameters). 

3.4. Array Declarations 

Arrays may now have as many as seven dimensions. (Only three were 
permitted in 1966). The lower bound of each dimension may be declared 
to be other than 1 by using a colon. Furthermore, an adjustable array 
bound may be an integer expression involving constants, arguments, and 
variables in common. 

real a(-5:3, 7, m:n), b(n+l:2*n) 

The upper bound on the last dimension of an array argument may be 
denoted by an asterisk to indicate that the upper bound is not specified: 

integer a(5, •), b(*), c(0:l, -2:*) 

3.5. SAVE Statement 

A poorly known rule of Fortran 66 is that local variables in a procedure 
do not necessarily retain their values between invocations of that pro¬ 
cedure. At any instant in the execution of a program, if a common block 
is declared neither in the currently executing procedure nor in any of 
the procedures in the chain of callers, all of the variables in that com¬ 
mon block also become undefined. (The only exceptions are variables 
that have been defined in a data statement and never changed). These 
rules permit overlay and stack implementations for the affected vari¬ 
ables. Fortran 77 permits one to specify that certain variables and com¬ 
mon blocks are to retain their values between invocations. The declara¬ 
tion 


save a, /b/, c 

leaves the values of the variables a and c and all of the contents of com¬ 
mon block b unaffected by a return. The simple declaration 

save 

has this effect on all variables and common blocks in the procedure. A 
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common block must be saved in every procedure in which it is declared if 
the desired effect is to occur. 

3.6. INTRINSIC Statement 

All of the functions specified in the Standard are in a single category, 
“intrinsic functions", rather than being divided into "intrinsic" and 
"basic external" functions. If an intrinsic function is to be passed to 
another procedure, it must be declared intrinsic. Declaring it external 
(as in Fortran 66) causes a function other than the built-in one to be 
passed. 

4. Expressions 

4.1. Character Constants 

Character string constants are marked by strings surrounded by apos¬ 
trophes. If an apostrophe is to be included in a constant, it is repeated: 

'abc' 

'ain"t‘ 

There are no null (zero-length) character strings in Fortran 77. Our 
compiler has two different quotation marks, " * and " " ". (See Section 
2.9 in the main text.) 

4.2. Concatenation 

One new operator has been added, character string concatenation, 
marked by a double slash ("//”). The result of a concatenation is the 
string containing the characters of the left operand followed by the 
characters of the right operand. The strings 

■ab’ // *cd' 

‘abed’ 

are equal. The strings being concatenated must be of constant length in 
all concatenations that are not the right sides of assignments. (The only 
concatenation expressions in which a character string declared adju¬ 
stable with a "♦(•)" modifier or a substring denotation with nonconstant 
position values may appear are the right sides of assignments). 

4.3. Character String Assignment 

The left and right sides of a character assignment may not share 
storage. (The assumed implementation of character assignment is to 
copy characters from the right to the left side.) If the left side is longer 
than the right, it is padded with blanks. If the left side is shorter than 
the right, trailing characters are discarded. 

4.4. Substrings 

It is possible to extract a substring of a character variable or character 
array element, using the colon notation: 

a(i.j) (m:n) 

is the string of (n-m+1) characters beginning at the m 0> character of the 
character array element ay. Results are undefined unless m«n. Sub¬ 
strings may be used on the left sides of assignments and as procedure 
actual arguments. . 
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4.5. Exponentiation 

It is now permissible to raise real quantities to complex powers, or com¬ 
plex quantities to real or complex powers. (The principal part of the log¬ 
arithm is used). Also, multiple exponentiation is now defined: 

a**b**c = a •• (b»*c) 

4.6. Relaxation of Restrictions 

Mixed mode expressions are now permitted. (For instance, it is permissi¬ 
ble to combine integer and complex quantities in an expression.) 

Constant expressions are permitted where a constant is allowed, except 
in data statements. (A constant expression is made up of explicit con¬ 
stants and parameters and the Fortran operators, except for exponen¬ 
tiation to a floating-point power). An adjustable dimension may now be 
an integer expression involving constants, arguments, and variables in B 
common.. 

Subscripts may now be general integer expressions; the old cvtc' rules 
have been removed, do loop bounds may be general integer, real, or dou¬ 
ble precision expressions. Computed goto expressions and 1/0 unit 
numbers may be general integer expressions. 

5. Executable Statements 

5.1. IF-THEN-ELSE 

At last, the if-then-else branching structure has been added to Fortran. 
It is called a "Block If". A Block If begins with a statement of the form 

if ( . . . ) then 

and ends with an 

end if 

statement. Two other new statements may appear in a Block If. There 
may be several 

else if(.. .) then 

statements, followed by at most one 
else 

statement. If the logical expression in the Block If statement is true, the 
statements following it up to the next elseif, else, or endif are executed. 
Otherwise, the next elseif statement in the group is executed. If none of 
the sh: It: not found elseif conditions are true, control passes to the 
statements following the else statement, if any. (The else must follow all 
elseifs in a Block If. Of course, there may be Block Ifs embedded inside 
of other Block If structures). A case construct may be rendered 

if (s .eq. 'ab') then 
else if (s .eq. 'cd') then 
else 
end if 
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5.2. Alternate Returns 

Some of the arguments of a subroutine call may be statement labels pre¬ 
ceded by an asterisk, as in 

call joe(j, *10, m, *2) 

A return statement may have an integer expression, such as 
return k 

If the entry point has n alternate return (asterisk) arguments and if 
lsfcsn, the return is followed by a branch to the corresponding statement 
label; otherwise the usual return to the statement following the call is 
executed. 

6. Input/Output 

6.1. Format Variables 

A format may be the value of a character expression (constant or other¬ 
wise), or be stored in a character array, as in 

write(6, ’(i5)’) x 

6.2. END=. ERR=, and I0STAT= Clauses 

A read or write statement may contain end=, err=, and iostat= clauses, 
as in 

write(6, 101, err=20, iostat=a(4)) 
read(5, 101, err=20, end=30, iostat=x) 

Here 5 and 6 are the units on which the I/O is done, 101 is the statement 
number of the associated format, 20 and 30 are statement numbers, and 
a and x are integers. If an error occurs during 1/0, control returns to 
the program at statement 20. If the end of the file is reached, control 
returns to the program at statement 30. In any case, the variable 
referred to in the iostat= clause is given a value when the 1/0 statement 
finishes. (Yes, the value is assigned to the name on the right side of the 
equal sign.) This value is zero if all went well, negative for end of file, and 
some positive value for errors. 

6.3. Formatted I/O 

6.3.1. Character Constants 

Character constants in formats are copied literally to the output. Char¬ 
acter constants cannot be read into. 

write (6, 1 ’02" isn’’"t ",il)') 7, 4 

produces 

7 isn't 4 

Here the format is the character constant 
(i2,’ isn"t \il) 

and the character constant 


isn't 
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is copied into the output. 

6.3.2. Positional Editing Codes 

t, tl, tr, and x codes control where the next character is in the record, 
tm or nx specifies that the next character is n to the right of the 
current position, tin. specifies that the next character is n to the left of 
the current position, allowing parts of the record to be reconsidered, tn 
says that the next character is to be character number n in the record. 
(See section 3.4 in the main text.) 

6.3.3. Colon 

A colon in the format terminates the I/O operation if there are no more 
data items in the I/O list, otherwise it has no effect. In the fragment 

x='("hello", " there”, i4)' 
write (6. x) 12 
write(6, x) 

the first write statement prints hello there 12. while the second only 
prints hello. 

6.3.4. Optional Plus Signs 

According to the Standard, each implementation has the option of put¬ 
ting plus signs in front of non-negative numeric output. The sp format 
code may be used to make the optional plus signs actually appear for all 
subsequent items while the format is active. The ss format code guaran¬ 
tees that the I/O system will not insert the optional plus signs, and the s 
format code restores the default behavior of the I/O system. (Since we 
never put out optional plus signs, ss and s codes have the same effect in 
our implementation.) 

6.3.5. Blanks on Input 

Blanks in numeric input fields, other than leading blanks will be ignored 
following a bn code in a format statement, and will be treated as zeros 
following a bz code in a format statement. The default for a unit may be 
changed by using the open statement. (Blanks are ignored by default.) 

6.3.6. Unrepresentable Values 

The Standard requires that if a numeric item cannot be represented in 
the form required by a format code, the output field must be filled with 
asterisks. (We think this should have been an option.) 

6.3.7. Iw.m 

There is a new integer output code, iw.m. It is the same as iiu, except 
that there will be at least m digits in the output field, including, if neces¬ 
sary, leading zeros. The case it«.0 is special, in that if the value being 
printed is 0, the output field is entirely blank, itu.l is the same as iu;. 

6.3.8. Floating Point 

On input, exponents may start with the letter E, D, e, or d. All have the 
same meaning. On output we always use e. The e and d format codes 
also have identical meanings. A leading zero before the decimal point in 
e output without a scale factor is optional with the implementation. (We 
do not print it.) There is a giu.d format code which is the same as ew.d 
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and fw.d on input, but which chooses f or e formats for output depend¬ 
ing. on the size of the number and of d. 

6.3.9. "A" Format Code 

A codes are used for character values, atu use a field width of w, while a 
plain a uses the length of the character item. 

6.4. Standard Units 

There are default formatted input and output units. The statement 
read 10, a, b 

reads from the standard unit using format statement 10. The default 
unit may be explicitly specified by an asterisk, as in 

read(*, 10) a,b 

Similarly, the standard output units is specified by a print statement or 
an asterisk unit: 

print 10 
write(*. 10) 

6.5. list-Directed Formatting 

List-directed 1/0 is a kind of free form input for sequential I/O. It is 
invoked by using an asterisk as the format identifier, as in 

read(6, •) a.b.c 

On input, values are separated by strings of blanks and possibly a 
comma. Values, except for character strings, cannot contain blanks. 
End of record counts as a blank, except in character strings, where it is 
ignored. Complex constants are given as two real constants separated 
by a comma and enclosed in parentheses. A null input field, such as 
between two consecutive commas, means the corresponding variable in 
the I/O list is not changed. Values may be preceded by repetition 
counts, as in 

4*(3.,2.) 2*. 4*’hello' 

which stands for 4 complex constants, 2 null values, and 4 string con¬ 
stants. 

For output, suitable formats are chosen for each item. The values of 
character strings are printed; they are not enclosed in quotes, so they 
cannot be read back using list-directed input. 

6.6. Direct I/O 

A file connected for direct access consists of a set of equal-sized records 
each of which is uniquely identified by a positive integer. The records 
may be written or read in any order, using direct access 1/0 statements. 

Direct access read and write statements have an extra argument, rec=, 
which gives the record number to be read or written. 

read(2, rec=13, err=20) (a(i), i=l, 203) 

reads the thirteenth record into the array a. 
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The size of the records must be given by an open statement (see below). 
Direct access files may be connected for either formatted or unformat¬ 
ted 1/0. 

6.7. Internal Files 

Internal files are character string objects, such as variables or sub¬ 
strings, or arrays of type character. In the former cases there is only a 
single record in the file, in the latter case each array element is a 
record. The Standard includes only sequential formatted I/O on internal 
files. (I/O is not a very precise term to use here, but internal files are 
dealt with using read and write). There is no list-directed 1/0 on internal 
files. Internal files are used by giving the name of the character object 
in place of the unit number, as in 

character*80 x 
read(5,"(a)") x 
read(x,"(i3,i4)") nl,n2 

which reads a card image into x and then reads two integers from the 
front of it. A sequential read or write always starts at the beginning of 
an internal file. 

(We also support a compatible extension, direct 1/0 on internal files. 
This is like direct I/O on external files, except that the number of 
records in the file cannot be changed.) 

6.8. OPEN, CLOSE, and INQUIRE Statements 

These statements are used to connect and disconnect units and files, 
and to gather information about units and files. 

6.8.1. OPEN 

The open statement is used to connect a file with a unit, or to alter some 
properties of the connection. The following is a minimal example. 

open(l, file=’fort.junk') 

open takes a variety of arguments with meanings described below. 

unit= a small non-negative integer which is the unit to which the file is to 
be connected. We allow, at the time of this writing, 0 through 18. If 
this parameter is the first one in the open statement, the unit= can 
be omitted. 

iostat= is the same as in read or write. 
err= is the same as in read or write. 

file= a character expression, which when stripped of trailing blanks, is 
the name of the file to be connected to the unit. The filename 
should not be given if the status=scratch. 

status= one of old, new, scratch, or unknown. If this parameter is not 
given, unknown is assumed. If scratch is given, a temporary file will 
be created. Temporary files are destroyed at the end of execution. 
If new is given, the file must not exist. If old is given, it must exist. 
The meaning of unknown is processor dependent; our system opens 
the file if it exists and creates it otherwise. 






- 19- 


access= sequential (default) or direct, depending on whether the file is 
to be opened for sequential or direct 1/0. 

form= formatted or unformatted. If this parameter is not given, format¬ 
ted is assumed for a sequential file and unformatted for a direct- 
access file. 

recl= a positive integer specifying the record length of the direct access 
file being opened. We measure all record lengths in bytes. On UNlXf 
systems a record length of 1 has the special meaning explained in 
section 5.1 of the text. 

blank= null or zero. This parameter has meaning only for formatted I/O. 
The default value is null, zero means that blanks, other than lead¬ 
ing blanks, in numeric input fields are to be treated as zeros. 

Opening a new file on a unit which is already connected has the effect of 
first closing the old file. Note that the file pointer is positioned at the 
end of a sequential file; for reading the file must be rewound. 

6.8.2. CLOSE 

close severs the connection between a unit and a file. The unit number 
must be given. The optional parameters are iostat= and err= with their 
usual meanings, and status= either keep or delete. Scratch files cannot 
be kept, otherwise keep is the default, delete means the file will be 
removed. A simple example is 

close(3, err=17) 

6.8.3. INQUIRE 

The inquire statement gives information about a unit ("inquire by unit") 
or a file ("inquire by file”). Simple examples are: 

inquire(unit=3, namexx) 
inquire(file=’junk', number=n, exist=l) 

file= a character variable specifies the file the inquire is about. Trailing 
blanks in the file name are ignored. 

unit= an integer variable specifies the unit the inquire is about. Exactly 
one of file= or unit= must be used. 

iostat=, err= are as before. 

exist= a logical variable. The logical variable is set to .true, if the file or 
unit exists and is set to .false, otherwise. 

opened= a logical variable. The logical variable is set to .true, if the file 
is connected to a unit or if the unit is connected to a file, and it is 
set to .false, otherwise. 

number= an integer variable to which is assigned the number of the unit 
connected to the file, if any. 

named= a logical variable to which is assigned .true, if the file has a 
name, or .false, otherwise. 


|UN1X is a Trademark of Bell Laboratories. 
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name= a character variable to which is assigned the name of the file 
(inquire by file) or the name of the file connected to the unit 
(inquire by unit). The name will be the full name of the file. 

access= a character variable to which will be assigned the value 'sequen- 
tiaJ’ if the connection is for sequential I/O, 'direct' if the connection 
is for direct I/O. The value becomes undefined if there is no connec¬ 
tion. 

sequential a character variable to which is assigned the value 'yes' if 
the file could be connected for sequential I/O, 'no' if the file could 
not be connected for sequential I/O, and 'unknown' if we can't tell. 

direct= a character variable to which is assigned the value 'yes' if the file 
could be connected for direct I/O, 'no' if the file could not be con¬ 
nected for direct I/O, and 'unknown' if we can’t tell. 

form= a character variable to which is assigned the value 'formatted' if 
the file is connected for formatted I/O, or 'unformatted' if the file is 
connected for unformatted I/O. 

formatted= a character variable to which is assigned the value ’yes' if 
the file could be connected for formatted I/O, 'no' if the file could 
not be connected for formatted I/O, and 'unknown' if we can’t tell. 

unformatted= a character variable to which is assigned the value 'yes' if 
the file could be connected for unformatted I/O, 'no' if the file could 
not be connected for unformatted I/O, and 'unknown* if we can’t 
tell. 

recl= an integer variable to which is assigned the record length of the 
records in the file if the file is connected for direct access. 

nextrec= an integer variable to which is assigned one more than the 
number of the last record read from a file connected for direct 
access. 

blank= a character variable to which is assigned the value 'null’ if null 
blank control is in effect for the file connected for formatted 1/0, 
'zero' if blanks are being converted to zeros and the file is con¬ 
nected for formatted 1/0. 

The gentle reader will remember that the people who wrote the standard 
probably weren’t thinking of his needs. Here is an example. The declarations 
are omitted. 

open(l, file=''/dev/console") 

On a UNIX system this statement opens the console for formatted sequential 
I/O. An inquire statement for either unit 1 or file "/dev/console" would 
reveal that the file exists, is connected to unit 1, has a name, namely 
''/dev/console", is opened for sequential I/O, could be connected for sequen¬ 
tial I/O, could not be connected for direct I/O (can’t seek), is connected for 
formatted 1/0, could be connected for formatted I/O, could not be connected 
for unformatted I/O (can’t seek), has neither a record length nor a next 
record number, and is ignoring blanks in numeric fields. 

In the UNIX system environment, the only way to discover what permis¬ 
sions you have for a file is to open it and try to read and write it. The err= 
parameter will return system error numbers. The inquire statement does not 
give a way of determining permissions. 
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1. Introduction 

ADB is a debugging program that is available on UNIX. It provides capabilities to 
look at “core" files resulting from aborted programs, print output in a variety 
of formats, patch files, and run programs with embedded breakpoints. This 
document provides examples of the more useful features of ADB. The reader is 
expected to be familiar with the basic commands on UNIX t .with the C 
language, and with References 1, 2 and 3. 

2. A Quick Survey 

2.1. Invocation 
ADB is invoked as: 

adb objfile corefile 

where objf i le is an executable UNIX file and corefile is a core image file. Many 
times this will look like: 

adb a.out core 

or more simply: 

acb 

where the defaults are a. out and core respectively. The filename minus (—) 
means ignore this argument as in: 

acb - core 

ADB has requests for examining locations in either file. The ? request examines 
the contents of objfi I e, the / request examines the corefile. The general 
form of these requests is: 

address ? format 


or 

address / format 

2.2. Current Address 

ADB maintains a current address, called dot, similar in function to the current 
pointer in the UNIX editor. When an address is entered, the current address Is 
set to that location, so that: 

#126?i 

sets dot to hex 126 and prints the instruction at that address. The request: 
fUNIX is a Trademark of Bell Laboratories. 
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..10/d 

prints 10 decimal numbers starting at dot. Dot ends up referring to the address 
of the last item printed. When used with the ? or / requests, the current 
address can be advanced by typing newline; it can be decremented by typing 

Addresses are represented by expressions. Expressions are made up from 
decimal, octal, and hexadecimal integers, and symbols from the program under 
test. These may be combined with the operators +, -, *, % (integer division), ic 
(bitwise and), | (bitwise inclusive or), # (round up to the next multiple), and ~ 
(not) (internal arithmetic uses 32 bits). When typing a symbolic address for a C 
program, the user can type name or _name; ADB will recognize both forms. 

2.3. Formats 

To print data, a user specifies a collection of letters and characters that 
describe the format of the printout. Formats are ''remembered" in the sense 
that typing a request without one will cause the new printout to appear in the 
previous format. The following are the most commonly used format letters. 

b one byte in octal _ 

c one byte as a character 
o one word in octal 

d one word in decimal 

f two words in floating point 

i MC68000 instruction 

s a null terminated character string 
a the value of dot 

u one word as unsigned integer 

n print a newline 

r print a blank space 

- backup dot 

(Format letters are also available for "long" values, for example, ’D’ for long 
decimal, ‘X* for long hex. and ‘F* for double floating point.) For other formats 
see the ADB manual. 


2.4. General Request Meanings 
The general form of a request is: 

address,count command modifier 


which sets *dot‘ to address and executes the command count times. 
The following table illustrates some general ADB command meanings: 


Command 

? 

/ 

S 

I 


Meaning 

Print contents from a. out file 
Print contents from core file 
Print value of "dot" 
Breakpoint control 
Miscellaneous requests 
Request separator 
Escape to shell 
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ADB catches signals, so a user cannot use a quit signal to exit from ADB. The 
request Sq or SQ (or crtl-Z) must be used to exit from ADB. 

3. Debugging C Programs 

3.1. Debugging A Core Image 

Consider the C program in Figure 1. The program is used to illustrate a com¬ 
mon error made by C programmers. The object of the program is to change the 
lower case "t" to upper case in the string pointed to by charp and then write the 
character string to the file indicated by argument 1. The bug shown is that the 
character ”T" is stored in the pointer charp instead of the string pointed to by 
charp. Executing the program produces a core file because of an out of bounds 
memory reference. 

ADB is invoked by: 

acb a. out core 
The first debugging request: 

Sc 

is used to give a C backtrace through the subroutines called. As shown in Fig¬ 
ure 2 only one function (main) was called and the arguments argc and argv have 
hex values #2 and #efff4e respectively. Both of these values look reasonable; #2 
= two arguments, #efff4e = address on stack of parameter vector. 

The next request: 

SC 

is used to give a C backtrace plus an interpretation of all the local variables in 
each function and their values in hex. Note that of the value for cc only the 
first byte is significant, because cc is declared as char. Were it declared as 
short, only the first two bytes would be significant. If however cc would have 
been declared as register char or register short, the name cc would have been 
prefixed with a ’<’, the shown value would be the value of the register, and the 
significant byte or word would be the last byte or word of the value! 

The next request: 

Sr 

prints out the registers including the program counter and an interpretation of 
the instruction at that location. 

The request: 

Se 

prints out the values of all external variables. 

A map exists for each file handled by ADB. The map for the a. out file is refer¬ 
enced by ? whereas the map for core file is referenced by /. Furthermore, a 
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good rule of thumb is to use ? for instructions and / for data when looking at 
programs. To print out information about the maps type: 

*m 

This produces a report of the contents of the maps. More about these maps 
later. 

In our example, it is useful to try to see the contents of the string pointed to by 
charp. This is done by: 

*charp/s 

which says use charp as a pointer in the core file and print the information as a 
character string. This gives the message ‘data address not found', because #55 
is not a valid data address. Using ADB similarly, we could print information 
about the arguments to a function. The request: 

main.argc/d 

prints the decimal core image value of the argument argc in the function main. 
The request: 

*main."argv/3X 

prints the long hex values of the three consecutive pointers pointed to by argv 
in the function main. Note that these values are the addresses of the argu¬ 
ments to main. Therefore: 

#efff7a/s 

prints the ASCII value of the first argument. Another way to print this value 
would have been 

*"/s 

The " means ditto which remembers the last address typed, in this case 
main.argc ; the • instructs ADB to use the address field of the core file as a 
pointer. 

The request: 

.-X 

prints the current address (not its contents) in long hex which has been set to 
the address of the first argument. The current address, dot, is used by ADB to 
"remember" its current location. It allows the user to reference locations rela¬ 
tive to the current address, for example: 

.-10/d 
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3.2. Multiple Functions 

Consider the C program illustrated in Figure 3. This program calls functions 
f.g, and h until the stack is exhausted and a core image is produced. This 
example is a bit dangerous. On a system with a 68000, which does not generally 
recover from stack overflows, the program will sooner or later crash. With a 
68010, however, the stack may grow very very large! 

Again you can enter the debugger via: 
acts 

which assumes the names a. out and core for the executable file and core image 
file respectively. The request: 

Sc 

will fill a page of backtrace references to f.o, and h. Figure 4 shows an 
abbreviated list (typing Ctrl-C will terminate the output and bring you back to 
ADB request level). 

The request: 

,5SC 

prints the five most recent activations. 

Notice that each function (f.g.h) has a counter of the number of times it was 
called. 

The request: 

fcnt/d 

prints the decimal value of the counter for the function f. Similarly gent and 
hent could be printed. To print the value of an automatic variable, for example 
the decimal value of x in the last call of the function h, type: 

h.x/d 

It is not possible to print stack frames other than the most recent activation of 
a function. Therefore, a user can print everything with SC or the occurrence of 
a variable in the most recent call of a function. It is possible with the SC 
request, however, to print the stack frame starting at some address as 
addressSC. 

3.3. Setting Breakpoints 

Consider the C program in Figure 5. This program, which changes tabs into 
blanks, is adapted from Software Tools by Kernighan and Plauger, pp. 18-27. 

We will run this program under the control of ADB (see Figure 6) by: 
aefa a.out - 

Breakpoints are set in the program as: 
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address:b [request] 

The requests: 

settab+4:b 

fopen+4:b 

getc+4:b 

tabpos+4:b 

set breakpoints at the start of these functions, except for getc, which is called 
as a function, but in reality a macro defined in <stdio.h>. With the C compiler 
option -g, C generates statement labels. So it would be possible to plant a 
breakpoint at line 32 with the command 

L32:b 

The above addresses are entered as 
symbo 14-4 

so that they will appear in any C backtrace since the first instruction of each 
function is the 68000 LINK instruction. If you want to see the correct values of 
the register variables, if any, in the topmost procedure, you have to set the 
breakpoint after the MOVEM instruction which comes second. Note that some of 
the functions are from the C library. 

To print the location of breakpoints one types: 

Sb 

The display indicates a count field. A breakpoint is bypassed count —ltimes 
before causing a stop. The command field indicates the ADB requests to be exe¬ 
cuted each time the breakpoint is encountered. In our example no command 
fields are present. 

By displaying the original instructions at the function settab we see that the 
breakpoint is set after the LINK instruction. We can display the instructions 
using the ADB request: 

settab,5?ia 

This request displays five instructions starting at 6ettab with the addresses of 
each location displayed. Another variation is: 

settab,5?i 

which displays the instructions with only the starting address. 

Notice that we accessed the addresses from the a. out file with the ? command. 
In general when asking for a printout of multiple items, ADB will advance the 
current address the number of bytes necessary to satisfy the request; in the 
above example five instructions were displayed and the current address was 
advanced 20 (decimal) bytes. 
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To run the program one simply types: 

:r 

To delete a breakpoint, for instance the entry to the function settab, one 
types: 

settab+4:d 

To continue execution of the program from the breakpoint type: 


: c 

Once the program has stopped (in this case at the breakpoint for fopen), ADB 
requests can be used to display the contents of memory. For example: 

SC 

to display a stack trace, or: 
tabs,3/8d 

to print three lines of 8 locations each from the array called tabs. By this time 
(at location fopen) in the C program, settab has been called and should have 
set a one in every eighth location of tabs. 

3.4. Advanced Breakpoint Usage 

We recompile the program, this time with the -g and -L option: 
cc -g -L figureS.c 

The -g option will add symbols Li to the symbol table of the program which point 
to the code for line i. The -L option adds code to the program itself, that writes 
the current line number into the stackframe. If you set a breakpoint to Li, than 
the code for writing i into the stackframe will probably be executed next. 

Now we start adb again, setting breakpoints to line 24, after the getc and just in 
front of the switch statement, and to the start of tabpos. See figure 7. The first 
breakpoint shall be executed three times, each time displaying the value of c as 
a character. When the tabpos breakpoint is reached, we want to have a full 
dump of the topmost stackframe. The file "data" contains the text 
"This<tab>is<tab>a...'\ 

act} a. out - 
L24,3:b main.c-l/C 
tabpos+4:b .ISC 

:r ~ 

The program starts, displaying the value of c three times, and then stops. When 
we continue the program with: 

:c 
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the L24 breakpoint is executed two more times, then we hit our breakpoint at 
tabpos since there is a tab following the "This" word of the data. 

We see that tabpos is called with a value of 5. The displayed linenumber is 
incorrect because the code for storing the linenumber is not yet executed. 
Next we want to set a breakpoint at the end of the procedure. We could use the 
linenumber again, but for demonstration we are searching for the UNLK 
instruction at the end of the procedure, which has the opcode #4e5e, and set a 
breakpoint to it. The command 

?l jjfteSe 

searches from the current value of dot, which is set (in this case) to tabpos+4, 
until it finds the value #4e5e. This value is reported to be at location 
tabpos+#2e, and dot is set to this address. With :b we set a breakpoint to dot, 
and with :c we continue. When we reach the breakpoint, we can look at the 
value tabpos returns, by displaying the contents of register DO. A final view of 
the active frames with SC shows us, that main is executing line 26 and tabpos 
line 49. 

The UNIX quit and interrupt signals act on ADB itself rather than on the pro¬ 
gram being debugged. If such a signal occurs then the program being debugged 
is stopped and control is returned to ADB. The signal is saved by ADB and is 
passed on to the test program if: 


:c 

is typed. This can be useful when testing interrupt handling routines. The sig¬ 
nal is not passed on to the test program if: 

: c 0 

is typed. 

A breakpoint can be overwritten without first deleting the old breakpoint. For 
example: 

settab+4:b 6ettab,5?ia; ptab/x 
could be entered after typing the above requests. 

3.5. Other Breakpoint Facilities 

• Arguments and change of standard input and output are passed to a pro¬ 
gram as: 

:r argl arg2 ... <infile >outfile 

This request kills any existing program under test and starts the a. out 
afresh. 

• The program being debugged can be single stepped by: 

: 8 
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If necessary, this request will start up the program being debugged and 
stop after executing the first instruction. 

ADB allows a program to be entered at a specific address by typing: 
address:r 

The count field can be used to skip the first n breakpoints as: 

,n:r 

The request: 

,n:c 

may also be used for skipping the first n breakpoints when continuing a 
program. 

A program can be continued at an address different from the breakpoint 
by: 

address:c 

The program being debugged runs as a separate process and can be killed 
by: 

:k 


4. Maps 

UNIX knows several object file formats. These are used to tell the loader how to 
load the program file. File type 407 is the format of object modules generated 
by a C compiler invocation such as cc -c pgm.c. A 411 file is produced by the 
loader, when all references are resolved. This is the format of all executable 
files. ADB provides access to the program or module through a set of maps. To 
print the maps type: 

Sm 


The b, e, and f fields are used by ADB to map addresses into file addresses. The 
"b" and "e" fields are the starting and ending locations for a segment, i.e. logi¬ 
cal addresses. When an address A followed by ? or / is given, adb goes to the 
specified map, and sees if A lies in the interval [bl.el] or [b2,e2]. If yes, it sub¬ 
tracts the corresponding b value from A and adds the corresponding f value, to 
obtain the physical address in the file. More formally, given an address, A. the 
location in the file (either a. out or core) is calculated as: 

bl<A:3Bl * file address » (A-bl)+fl 

b2^A^a2 » file address - (A-b2)+f2‘ 
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In the normal case, the first segment of the ? map corresponds to the a.out 
text, the second to the a.out data. The first segment of the / map corresponds 
to the core data segment, and the second segment to the core stack segment. A 
core file does not include the text of the crashed program. Note that data can 
be accessed in two ways. However, the a.out data segment is the data segment 
as it looked at load time. It also contains only the initialized data. The core data 
segment is the data at the time of the core dump. Note that the b2 value of the 
/ map is the lower limit of the stack. 

A user can access locations by using the ADB defined variables. The Sv request 
prints the variables initialized by ADB (Figure 8): 

b base address of data segment 
d length of the data segment 
c entry point of the program 

m execution type (407,410,411) 

s length of the stack 

t length of the text 

Use can be made of these variables by expressions such as: 

<s 

in the address field. Similarly the value of the variable can be changed by an 
assignment request such as: 

02000 *) 

that sets b to octal 2000. These variables are useful to know if the file under 
examination is an executable or core image file. 

ADB reads the header of the core image file to find the values for these vari¬ 
ables. If the second file specified does not seem to be a core file, then standard 
values for identical mapping are used instead. 

5. Advanced Usage 

It is possible with ADB to combine formatting requests to provide elaborate 
displays. Below are several examples. 

5.1. Formatted dump 
The line: 

-1/4x4~8Cn 

prints 4 hex words followed by their ASCII interpretation from the data space of 
the core image file. Broken down, the various request pieces mean: 

<b The base address of the data segment. 

<b-1 

Print from the base address to the end of file. A negative count is used 
here and elsewhere to loop indefinitely or until some error condition (like 
end of file) is detected. 
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The format 4x4~8Cn is broken down as follows: 

4x Print 4 hex locations. 

4~ Backup the current address 4 locations (to the original start of the field). 

8C Print 8 consecutive characters using an escape convention: each character 
in the range 0 to 037 is printed as @ followed by the corresponding charac¬ 
ter in the range 0140 to 0177. An @ is printed as @@. 

n Print a newline. 

The request: 

<£>, <jd/4x4-8Cn 

could have been used instead to allow the printing to stop at the end of the 
data segment (<d provides the data segment size in bytes). 

The formatting requests can be combined with ADB's ability to read in a script 
to produce a core image dump script. ADB is invoked as: 

adb a.out core < dump 

to read in a script file, dump, of requests. An example of such a script is: 

120Su 
4035*s 

Sv 

«3n 

Sm 

■3n’C Stack Backtrace" 

SC 

*3n’C External Variables" 

Se 

-3n’Registers" 

Sr 

0Ss 

«3n"0ata Segment" 

<3),-l/8xna 

ADB attempts to print addresses as: 
symbol + offset 

The request 4095Ss sets the maximum permissible offset to the nearest sym¬ 
bolic address to 4095 (default 32767). The request = can be used to print 
literal strings. Thus, headings are provided in this dump program with requests 
of the form: 

*3n’C Stack Backtrace" 

that spaces three lines and prints the literal string. The request Sv prints all 
non-zero ADB variables (see Figure 8). The request OSs sets the maximum offset 
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for symbol matches to zero thus suppressing the printing of symbolic labels in 
favor of hex values. Note that this is only done for the printing of the data seg¬ 
ment. Try dumping the data segment without changing the maximum offset for 
a comparison. The request: 

-l/8xna 

prints a dump from the base of the data segment to the end of file with a hex 
address field and eight hex numbers per line. 

Figure 10 shows the results of some formatting requests on the C program of 
Figure 9. 

5.2. Directory Dump 

As another illustration (Figure 11) consider a set of requests to dump the con¬ 
tents of a directory (which is made up of an integer i number followed by a 14 
character name): 

acftj dir - 

■n8t'Tnum"8t'tlame" 

0,-1? u8tl4cn 

In this example, the u prints the inumber as an unsigned decimal integer, the 8t 
means that ADB will space to the next multiple of 8 on the output line, and the 
14c prints the 14 character file name. 

5.3. Hist Dump 

Similarly the contents of the Hist of a file system, (e.g. /dev/hkO, see 
inode(5)) could be dumped with the following set of requests: 

adb /dev/hk0 - 

1024,-l?”f lags”8ton”l inko,uid,gid"8t3on",aize , 8tOn"addr”8tl0Xn"ti«ies"8t3Y2na 

In this example the dump begins at location 1024, since that is the start of an 
i I ist within a 5l2 byte per block file system. The last access time, last modify 
time and creation time are printed with the 3Y operator. Figure 11 shows por¬ 
tions of these requests as applied to a directory and file system. 

5.4. Converting values 

ADB may be used to convert values from one representation to another. For 
example: 

072 ■ odx 

will print 

072 58 #3a 

which are the octal, decimal and hexadecimal representations of 072 (octal). 
The format is remembered so that typing subsequent numbers will print them in 
the given formats. Character values may be converted similarly, for example: 

’a* ■ co 
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prints 


a 0141 

It may also be used to evaluate expressions but be warned that all binary opera¬ 
tors have the same precedence which is lower than that for unary operators. 

6. Patching 

Patching files with ADB is accomplished with the ur i te, w or If, request (which 
is not like the ed editor write command). This is often used in conjunction with 
the locate, 1 or L request. In general, the request syntax for 1 and w are similar 
as follows: 

?l value 

The request 1 is used to match on two bytes, L is used for four bytes. The 
request w is used to write two bytes, whereas W writes four bytes. The value 
field in either locate or write requests is an expression. Therefore, decimal, 
octal and hex numbers, or character strings are supported. 

In order to modify a file, ADB must be called as: 
adb -w fI lei 

When called with this option, f i lei is created if necessary and opened for both 
reading and writing. 

For example, consider the C program shown in Figure 9. We can change the 
word ’This" to "The " in the executable file for this program, ex7, by using the 
following requests: 

ad} -w ex7 - 
<b?l ’Th* 

?U ’The * 

The request ?1 starts at dot and stops at the first match of 'Th" having set dot 
to the address of the location found. Note the use of ? to write to the a. out file. 

More frequently the request will be typed as: 

?l *Th*; ?s 

and locates the first occurrence of "Th" and print the entire string. Execution 
of this ADB request will set dot to the address of the "Th" characters. 

As another example of the utility of the patching facility, consider a C program 
that has an internal logic flag. The flag could be set by the user through ADB 
and the program run. For example: 

adb a.out - 
:s argl arg2 
flag/u 1 
:c 
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The :s request is normally used to single step through a process or start a pro¬ 
cess in single step mode. In this case it starts a. out as a subprocess with argu¬ 
ments argl and arg2. If there is a subprocess running ADB writes to it rather 
than to the file so the w request causes flag to be changed in the memory of 
the subprocess. 

7. References 

1. D. M. Ritchie and K. Thompson, “The UNIX Time-Sharing System," CACM, 
July, 1974. 
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Figure 1: C program with pointer bug 

jjfinclude <stdio.h> 

char *charp - "this is a sentence."; 

FILE *obuf; 

main(argc,argv) 
int argc; 
char **argv; 

i 

char cc; 
if(argc < 2) \ 

printf("Output file argument missing\n"); 
exit(l); 

J 

i f ((obuf - fopen (argv II] f "u")) — NULL) f 

printfCls : not found\n" # argv ill); 
exit (1); 

cc - # X’; /* for OEHD purpose only */ 

charp - *1*; /* BUG; should be *charp - # T’; 

uhile(cc • *charp++) 

putc(cc.obuf); 
fclose(obuf); 


!! */ 
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Figure 2: ADB output for C program of Figure 1 

adb a.out core 
3c 

~main<#0e02.#08ef,(Pff4e,#00ef,#ff5a) line 0 


SC 

~inain{#0082.#00ef.#fff4e,#e0ef,#ffSa) line 0 
_argcs #080200ef 

argvt #00efff4e 

~cc: #S80880ef 


Sr 

d0 )j00800070 
dl #0080000c 
d2 #00600e3e 
d3 #00300000 
d4 #00080000 
d5 #00000000 


_i ob+#0024 

_charp+#0008 


d7 #00000000 

a0 #00SB0e40 

al #0080003a 

a2 #00000054 

a3 #00efff58 

a4 #00000000 

a5 #00000000 

a5 #00efffl8 

a7 #00effefc 

ns #00021d51 

ac #00000054 

ip #ldS20000 

pc #00G000e4 

-main+#0882: move.b 


_pharp+#003S 


~main+#0082 

(a2),-28(aG) 



Se 


^environ: 

<00eff f5a 


_charps 

<00000055 


_pbuf: 

<00800070 


_iob: 

<008005ca 


_lastbuf: 

<0080013c 


_sibuf: 

<00000000 


_80buf: 

<00000000 


_pfile: 

<00000000 


_errno: 

<00000000 


_ctypej 

<00202020 


_currbrks 

<00800dd0 


_end: 

<00000000 


Sm 

? map ’a,out’ 

bl - <00600000 

el - <0060126a 

fl - <0000001c 

b2 - <00808008 

e2 - <00800dd0 

f2 - <00001286 

/ map ’core* 

bl - <00800000 

el - <00800e00 

fl - <00000c54 

b2 - <00eff600 

e2 - <00f00000 

f2 - <00001a54 

charp/X 



_charp: <00000055 


*charp/s 

#08000065: 
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data address not found 


main.argc/d 

,f00efff20: 2 


•main.argv/3X 

#30efff4e: jj00efff7a #83eff18B 


#efff7a/s 

|B0efff7a: a.out 


•main.argv/3X 

|00ef f fAe: *00efff7a j(00efff80 


•"/S 

j)80efff7a: a. out 


.=x 

j$00eff f7a 


Sq 


1(00000000 


J 000000 00 
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Figure 3: Multiple function C program for stack trace illustration 

int fcnt.gcnt.hcnt; 
h(x v y) 

int hi; register int hr; 

hi • x+1; 

hr - x-y+1; 

hcnt++ ; 

hj: 

f(hr.hi); 


g (p* q) 

int gi; register int gr; 
gi . q-p; 
gr - q-p+1; 
gcnt-M- ; 

gjs 

h(gr,gi); 


f (a,b) 

int fi; register int fr; 
fi - a+2*b; 
fr » a+b; 
fcnt++ ; 
f i- 

g (f r, f i); 


mainO 

f (1.1); 

i 
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Figure 4: ADB output for C program of Figure 3 

adb 

Sc 

40840, #083 f) line 0 
(#8041,46080) line 0 
~f (#0882. #003f) line 0 
-h(4003e. )|003d) line 0 
~g(4833f,4007c) line 0 
~f (40082,4003d) I ine 0 
~h(4003c.4003b) lineO 
~g(4803d.#0078) Iine 0 
~f (40802.4003b) Iine 0 
-h(4083a,40033) line 0 
~g(<083b,<0074) Iine0 


HIT INTR KEY 

adb 


5SC 

4>(<8040,<e83f) line 8 

_hi: 

<Jnri 

-g (<0041. <0088) line 8 
— P* 

_gi: 

~f(40002.4003f)*nni 0 

j: 

_ta: 

_f i s 

<L.fr: 

~M<083e t #033d) line 8 

«y- 

_his 

<Lhr: 

-g(<083f.|807c) line 8 
-P J 
-PS 
Ji s 
^_gr: 


<0840883f 
<083f083f 
<00410000 
<08000802 

<08410080 
<08808880 
<003f0000 
<00000840 

<0802083 f 
<003f003 f 
<00880080 
<00880841 

<083e083d 
<003d003d 
<003f0000 
<00080002 

<003f087c 

<007c007c 

<003d0000 

<00000036 


fcnt/d 

_fcnt: 32 

gcnt/d 

_gcnt: 32 

hcnt/d 

_hcnt: 31 

h.x/d 

<08e ff826: 64 

8q 
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Figure 5: C program to decode tabs 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 
IB 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 
3B 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 


^include <stdio.h> 
fidei ine MAXLINE 80 
^define YES 1 

^define NO 0 

fide fine TABSP 8 


char 

FILE 

int 

mainO 

i 


input!] - "data"; 
*ibuf; 

tabs [MAXLINE]; 


int col, *ptab; 
char c; 

ptab - tabs; 

set tab(ptab)$ /sSet initial tab stops */ 
col - 1? 

if ((ibuf - fopen(input, "r")) — NULL) ( 
pr intfCls : not found\n". input) ; 
exit(l); 

while! (c • getc(ibuf)) !- ECF) } 
switch(c) { 

case *\t*: /* TAB */ 

whiIs(tabposCcol) !- YES) { 
putchar!* f ); 

col++ ; 

break; 

case *\n f : /*NEULIf€ */ 

putchar( f \n*); 
col - 1; 
break; 

default: 

putchar(c); 
col++ ; 

i 

\ J 

/* Tabpos return YES if col is a tab stop */ 

tabpos(col) 

int col; 

if (col > riAXLIhE) 

return(YES); 

else 

re turn(tabs CcoI]); 

i 

/* Settab - Set initial tab stops */ 

settab(tabp) 

int *tabp; 


\ 


int i; 
for (i ■ 


0; iO HAXLINEj i++) 
(iXTABSP) ? (tabsti] 


NO) : (tabsti) - YES); 
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Figure 6: ADB output for C program of Figure 5 

adb a.out - 
settab+4:b 
fopen+4:b 

getc+4:b 

symbol not found 


tabpos+4:b Sb 

breakpoints 

count bkpt command 

1 Mabpos+j)0004 

1 _fopen+#0004 

1 "-settab+#0004 


settab,5?ia 

^ettab: 

^ettab+jj8004s 

~settab+/!0808: 

''settab+#830e: 

''■set tab+#8310: 

^settab+^C014: 

1 ink 
clr.u 
cmpi •u 
bgt 

move.u 

36.6^28 
-28(a6) 
€80,-28(a6) 
r 'settab+#00S4 
-28(a6),dl 


settab,5?i 
^et tab: 

1 ink 
clr.u 
cmpi.u 
bgt 

move.u 

a6,^28 
-28 (a6) 
@0,-28(a6) 
~settab+#80S4 
-28(a6),dl 


:r 

a.out: running 
breakpoint 

^ettab+|J0004: clr.M 

-28(a6) 

settab+4:d 

:c 

a. out: running 
breakpoint 




_fopen*#0004: jsr 

_f Indiop 




SC 

_fopen(#0080, jS0004 f ,(0080. /)©00a) line 0 
^atn(^001,4&ef v #ff58,J00ef,#ffS0) line 8 
_coI: #000133ef 

_ptab: #808005ae 

_c: #00000080 


tabs,3/8d 

__tabs: 1 

1 
1 


0 0 0 
0 0 0 
0 0 0 


0 0 0 0 
0 0 0 0 
0 0 0 0 
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Figure 7: ADB output for C program of Figure 5 

adb a.out - 
L24,3:b main.c/C 
tabpos+4:b ,1SC 
:r 

a.out: running 
<00ef fefe: T 

<00effefe: h 

<00effefe: i 

breakpoint "main+<00c4: ext.w d0 


:c 

a.out: running 
<00effefe: 8 

<00effefe: @i 

~tabpos(<0005) line -224 

_col: <00050900 

breakpoint ~t a bpo s+<0004: move.w @47,-2(a6) 


?1 #4e5e 

~tabpo9+<002e 

:b 

:c 

a.out: running 

breakpoint ~tabpoa+<002e: unlk a6 


<dO=X 

<0000 


SC 

~tabpo9(<000S) line 49 

_poI: <00050900 

-fliain(<0001, <00ef,#ff5B # <00ef,#ff5e) line 2B 
_col: <000500ef 

_ptab: <008005ae 

_c: <09000080 
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Figure 8: ADB output for maps 


adb cat core 
Sm 

? map ’cat’ 

bl - $00802800 
b2 - $00800000 
/ map ’core 

bl - $00800808 
b2 - $00eff800 


Sv 

variables 
b - $00800000 
d - $00000300 
e - $00600800 
m - $00000109 
8 - $00080300 
t - $00001800 


el - $006017ee 
e2 - $008088d0 

el - $08800300 
e2 - $00f00000 


fl - $0000001C 
f2 - $0000180a 

fl - $00000c54 
f2 - $00001694 


Figure 9: Simple C program for illustrating formatting and patching 

char etrl [] - 'This is a character string"; 

int one - 1; 

int number • 456; 

long Inun - 1234; 

float fpt - 1.25; 

char 8tr2[] - 'This is the second character string"; 

mainO 

one - 2; 

i 
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Figure 10: ADB output illustrating fancy formats 

adb exlO - 


:s 

stopped at 

gentry: 


1 ink 

a6,@-26 




<b,6/8xna 

_execargs: 

*60ef 

#fffc 

*6468 

*6973 

*2069 

#7320 *6120 

*6368 

_strl+*008c: 

156172 

*6163 

#7465 

#7220 

#7374 

#7269 *6e67 

*6880 

_pne: 

_pne: 

*0001 

*01c8 

*6688 

*04d2 

#3000 

*0041 *5468 

*6973 

_str2+*6884: 

*2069 

#7320 

#7468 

*6520 

#7365 

*636f *6e64 

*2063 

_str2+*0014: 

*8861 

#7261 

*6374 

*6572 

*2073 

#7472 *696e 

*6780 

_iob: 

_iob: 

*0080 

*0148 

#8888 

*0080 

*0148 

*0100 *0000 

*6880 

<b,10/4x4~ 

_execargs: 

8Cn 

ii00ef 

*2069 

*6172 

#7374 

#fffc 

#7320 

*6163 

#7269 

*6468 

*6120 

#7465 

*Ge67 

*6973 

*6368 

#7220 

*0000 

®*o®|Thi8 
is a ch 
aracter 
string® 4 ®* 


_p ne: 

*0001 

*01c8 

<10000 

r /vvv 

<04d2 

®*®a€BH®*® 4 ®tf? 


_fp ts 

#3000 

#2069 

#7365 

*6861 

#2073 

*0041 
#7320 
*636f 
#7261 
#7472 

*6468 

#7468 

*6e64 

*6374 

*696e 

*6973 

*6520 

*2063 

*6572 

*6700 

®*@*AThis 
is the 
second c 
haracter 
string® 4 


<b,10/4x4~ 

_execargs: 

|This 

_strl+*6034: 

strl+*800c: 

_strl+*6014: 

_one: 

_pne: 

_f pt 2 

_f pt s 

str2+*6004: 

_str2+*600c: 

_str2+*8014: 

_str2+*601c: 

8t8cna 

*00ef - 

*2069 

*6172 

#7374 

*0001 

#fffc 

#7320 

*6163 

#7269 

*01c8 

*0041 
#7320 
*636f 
#7261 
#7472 

*6468 

*6120 

#7465 

*6e67 

40000 

*6973 

*6368 

#7220 

*0000 

*04d2 

*6973 

*6528 

*2063 

*6572 

*6700 


0 

is a ch 
aracter 
string 

..HR 

*(3000 

*2069 

#7365 

*8861 

*2073 

*5468 

#7468 

*6e64 

*6374 

*696e 


AThis 
is the 
second c 
haracter 
string 


<b,10/2b8t 

_execargs: 

1 

~2cn 
*0000 
*00 ff 

*00ef 

<00fC 


0 




_strl: 

*0054 

*0069 

*0020 

*0073 

*0061 

*0063 

*0061 

*0061 

*0068 

*0073 

*0069 

*0020 

*0020 

*0068 

*0072 

*0063 


Th 

is 

i 

8 
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ch 

ar 

ac 
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Figure 11: Directory and inode dumps 
adb dir - 

=nt"Inode"t"Name" 

0,6?utl4cn 

Inode Name 


renice 
shutdown.eh 
cron 
ddate 


1024,3?''flags''8ton'’links,uid,gid' , 8t3on'’size"8tDn''addr''8tl0Xn''times'' 

#80008400: flags 0108808 

Iinks.uid.gid 000 

addr #00888888 #00808888 #00888008 #08008800 

#00000080 #08000800 #00088080 #08808888 

#08080088 10 088 8880 

times 1384 Feb 8 17:42:14 1384 Feb 8 17:42:14 1384 Feb 


#08808808: 167 

1843 

334 

1331 

163 


adb /dev/hkO - 


#00888440: flags 048777 

I inks,uid,fid 05 0 0 

size 2832 

addr #08813308 #06 b3000f #42001333 #0818d580 

#/lffb0000 #00000080 #00080000 #00880888 

#00008000 #00000000 

times 1384 Oar 7 12:51:18 1384 Oar 7 15:23:53 1384 Mar 


#80880480: flags 0180755 

Iinks.uid,gid 01 02 02 

size 16368 

addr #00813308 #01418081 #4808814f #08815688 

#01Sd0001 #6408016b #08017208 #01738881 

#00808880 

times 1384 tlar 5 03:11:07 1383 Oct 12 13:00:28 1384 Feb 


adb 


8t3Y2na 


8 17:42:14 


7 15:23:53 


8 17:44:03 
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adb 


ADB Summary 


Command Summary 

a) formatted printing 

?format print from a. out file 

according to format 

/format print from core file accord¬ 
ing to format 


=format 
?w expr 


print the value of dot 


write expression into a. out 
file 


/w expr write expression into core 
file 


?1 expr locate expression in a. out 
file 

b) breakpoint and program control 

:b set breakpoint at dot 

:c continue running program 

:d delete breakpoint 

:k kill the program being debugged 

:r run a.out file under ADB control 

:s single step 


c) miscellaneous printing 

Jb print current breakpoints 

Sc C stack trace 

Se external variables 
Sf floating registers (not yet) 
Sm print ADB segment maps 

Sq exit from ADB 

Sr general registers 
Ss set offset for symbol match 

Sv print ADB variables 

Sw set output line width 


d) calling the shell 

! call she! I to read rest of line 

e) assignment to variables 

> name assign dot to variable or 
register name 


Format Summary 

a the value of dot 

b one byte in octal 

c one byte as a character 

d one word in decimal 

f two words in floating point 

i 66000 instruction 

o one word in octal 

n print a newline 

r print a blank space 

s a null terminated character string 
nt move to next n space tab 
u one word as unsigned integer 
x hexadecimal 

Y date 

~ backup dot 

print string 


Expression Summary 

a) expression components 


decimal integer 

octal integer 

hexadecimal 

symbols 

variables 

registers 

(expression) 


e.g. 256 
e.g. 0277 
e g- #ff 

e.g. _main main.argc 
e.g. <b 
e.g. <pc <d0 
expression grouping 


b) dyadic operators 

+ add 

— subtract 

• multiply 

% integer division 

& bitwise and 

| bitwise or 

§ round up to the next multiple 


c) monadic operators 
~ not 

* contents of location 
— integer negate 
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NAME 

adb - debugger 
SYNOPSIS 

adb [-w] [ objfil [ corfil ] ] 

DESCRIPTION 

Adb is a general purpose debugging program. It may be used 
to examine files and to provide a controlled environment for 
the execution of UNIX programs. 

Objfil is normally an executable program file, preferably 
containing a symbol table; if not then the symbolic features 
of adb cannot be used although the file can still be 
examined. The default for objfil is a.out. Corfil is 
assumed to be a core image file produced after executing 
objfil ; the default for corfil is core. 

Requests to adb are read from the standard input and 
responses are to the standard output. If the -w flag is 
present then both objfil and corfil are created if necessary 
and opened for reading and writing so that files can be 
modified using adb . Adb ignores QUIT; INTERRUPT causes 
return to the next adb command. 


In general requests to adb are of the form 


[ address ] [, count ] [ command ] [;] 

If address is present then dot is set to address . Initially 
dot is set to 0. For most commands count specifies how many 
times the command will be executed. The default count is 1. 
Address and count are expressions. 

The interpretation of an address depends on the context it 
is used in. If a subprocess is being debugged then 
addresses are interpreted in the usual way in the address 
space of the subprocess. For further details of address 
mapping see ADDRESSES. 

EXPRESSIONS 

. The value of dot. 


+ The value of dot incremented by the current 

increment. 

The value of dot decremented by the current 
increment. 

" The last address typed. 


integer 
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An octal number if integer begins with a 0; a 
hexadecimal number if preceded by #; otherwise a 
decimal number. 

integer . fraction 

A 32 bit floating point number. 

'£ccc' The ASCII value of up to 4 characters. \ may be used 
to escape a '. 

^ name The value of name, which is either a variable name or 
a register name. Adb maintains a number of variables 
(see VARIABLES) named by single letters or digits. 

If name is a register name then the value of the 
register is obtained from the system header in 
corfil . The register names are dO •.• d7 aO .•• a7 
pc ns ac ip. The register names ns, ac and ip 
deserve special explanation. The register ns is the 
concatenation of the 2 byte exception vector number 
plus the 2 byte 68000 cpustate stored during bus or 
address error exceptions. If e.g. the first two 
bytes of ns are 0002, the program was interrupted by 
a bus error (exception vector 2). The register ac 
contains the access address for a bus or address 
error exception. The register ip is the concatenation 
of the 2 byte instruction register, i.e. the first 
two bytes of the instruction that caused a bus or 
address error, and the 2 byte processor status. For 
exceptions that are not bus or address error, the 
second half of ns, all of ac, and the first half of 
ip are 0. 

symbol A symbol is a sequence of upper or lower case 

letters, underscores or digits, not starting with a 
digit. The value of the symbol is taken from the 
symbol table in objfil . An initial or ~ will be 
prepended to symbol if needed. 

_ symbol 

In C, the 'true name' of an external symbol begins 
with It may be necessary to utter this name to 
distinguish it from internal or hidden variables of a 
program. 

routine . name 

The address of the variable name in the specified C 
routine. Both routine and name are symbols. If name 
is omitted the value is the address of the most 
recently activated C stack frame corresponding to 
routine . 

( exp ) The value of the expression exp . 
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Monadic operators 


*exp 

The contents of the 
corfil. 

location 

addressed by 

@exp 

The contents of the 
objfil. 

location 

addressed by 

-exp 

Integer negation. 



~exp 

Bitwise complement. 




Dyadic operators are left associative and are less binding 
than monadic operators. 


el+e2 

Integer 

addition. 

el-e2 

Integer 

subtraction. 

e_L*e2 

Integer 

multiplication. 

el%e2 

Integer 

division. 

el&e2 

Bitwise 

conjunction. 

el | e2 

Bitwise 

disjunction. 

ej.#e2 

El rounded up to the next multiple of e2. 


COMMANDS 

Most commands consist of a verb followed by a modifier or 
list of modifiers. The following verbs are available. (The 
commands '?' and '/' may be followed by see ADDRESSES 

for further details.) 

?f_ Locations starting at address in objfil are printed 
according to the format f. 

/f Locations starting at address in corfil are printed 
according to the format f_. 

=f The value of address itself is printed in the styles 
indicated by the format _f. (For i format '?' is 
printed for the parts of the instruction that reference 
subsequent words.) 

A format consists of one or more characters that specify a 
style of printing. Each format character may be preceded by 
a decimal integer that is a repeat count for the format 
character. While stepping through a format dot is 
incremented temporarily by the amount given for each format 
letter. If no format is given then the last format is used. 
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The format letters available are as follows. 

o 2 Print 2 bytes in octal. All octal numbers output 
by adb are preceded by 0. 

0 4 Print 4 bytes in octal, 
q 2 Print in signed octal. 

Q 4 Print long signed octal, 
d 2 Print in decimal. 

D 4 Print long decimal, 
x 2 Print 2 bytes in hexadecimal. 

X 4 Print 4 bytes in hexadecimal, 
u 2 Print as an unsigned decimal number. 

U 4 Print long unsigned decimal. 

f 4 Print the 32 bit value as a floating point number. 

Currently only FFP format supported (see fp(3)). 

F 8 Print double floating point. For FFP same as 
above, except larger printing format, 
b 1 Print the addressed byte in octal, 
c 1 Print the addressed character. 

C 1 Print the addressed character using the following 
escape convention. Character values 000 to 040 
are printed as @ followed by the corresponding 
character in the range 0100 to 0140. The 
character @ is printed as @@. 
s n. Print the addressed characters until a zero 
character is reached. 

S n. Print a string using the @ escape convention, n 
is the length of the string including its zero 
terminator. 

Y 4 Print 4 bytes in date format (see ctime (3C)). 
i n Print as 68000 instructions, n is the number of 
bytes occupied by the instruction. This style of 
printing causes variables 1 and 2 to be set to the 
offset parts of the source and destination 
respectively. 

a 0 Print the value of dot in symbolic form. Symbols 
are checked to ensure that they have an 
appropriate type as indicated below. 

/ local or global data symbol 
? local or global text symbol 
= local or global absolute symbol 

p 2 Print the addressed value in symbolic form using 
the same rules for symbol lookup as a. 
t 0 When preceded by an integer tabs to the next 

appropriate tab stop. For example, 8t moves to 
the next 8-space tab stop, 
r 0 Print a space, 
n 0 Print a newline. 

"..." 0 

Print the enclosed string. 
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Dot is decremented by the current increment. 
Nothing is printed. 

+ Dot is incremented by 1. Nothing is printed. 
” decremented by 1. Nothing is printed. 


newline 

If the previous command temporarily incremented dot, 
make the increment permanent. Repeat the previous 
command with a count of 1. 

[?/]l value mask 

Words starting at dot are masked with mask and compared 
with value until a match is found. If L is used then 
the match is for 4 bytes at a time instead of 2. If no 
match is found then dot is unchanged; otherwise dot is 
set to the matched location. If mask is omitted then 
-1 is used. 

[?/]w value ••• 

Write the 2-byte value into the addressed location. If 
the command is W, write 4 bytes. Odd addresses are not 
allowed when writing to the subprocess address space. 

[?/]m bl el £1[?/] 

New values for (bl, el , f1 ) are recorded. If less than 
three expressions are given then the remaining map 
parameters are left unchanged. If the '?' or '/' is 
followed by then the second segment (b2,e2,f2) of 
the mapping is changed. If the list is terminated by 
'?' or '/' then the file ( objfil or corfil 
respectively) is used for subsequent requests. (So 
that, for example, '/m? 7 will cause '/' to refer to 
objfil.) 


>name 

Dot is assigned to the variable or register named. 


! A shell is called to read the rest of the line 
following '!'. 


$modifier 

Miscellaneous commands. The available modifiers are: 

<f_ Read commands from the file f_ and return. 

>f^ Send output to the file f_, which is created if it 
does not exist. 

r Print the general registers and the instruction 
addressed by pc. Dot is set to pc. 

b Print all breakpoints and their associated counts 
and commands. 

c C stack backtrace. If address is given then it is 
taken as the address of the current frame (instead 
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of a6). If C is used then the names and (32 bit) 
values of all automatic and static variables are 
printed for each active function. If count is 
given then only the first count frames are” 
printed. If the module was compiled with the -L 
option of cc(l), the procedure name is followed by 
the current linenumber. For all variables 32 bits 
are printed, even if the variable is only char or 
short. In this case only the foremost bytes are to 
be considered. For register variables, however, 
the whole register in which the variable resides 
is printed, and so for shorts the last two bytes 
are the relevant ones! In order to help you make 
the distinction between register and normal 
variables, the latter are prefixed with a "<". 

e The names and values of external variables are 
printed. 

w Set the page width for output to address (default 
80). 

s Set the limit for symbol matches to address 
(default 255). 

o All integers input are regarded as octal. 

d Reset integer input as described in EXPRESSIONS. 

q Exit from adb . 

v Print all non zero variables in octal. 

m Print the address map. 

imodifier 

Manage a subprocess. Available modifiers are: 

be Set breakpoint at address . The breakpoint is 
executed count -1 times before causing a stop. 

Each time the breakpoint is encountered the 
command c^ is executed. If this command sets dot 
to zero then the breakpoint causes a stop. If the 
module has been compiled with option -g, see 
cc(l), you can set a breakpoint at line 75 by 
saying L75:b. 

d Delete breakpoint at address . 

r Run objfil as a subprocess. If address is given 
explicitly then the program is entered at this 
point; otherwise the program is entered at its 
standard entry point, count specifies how many 
breakpoints are to be ignored before stopping. 
Arguments to the subprocess may be supplied on the 
same line as the command. An argument starting 
with < or > causes the standard input or output to 
be established for the command. All signals are 
turned on on entry to the subprocess. 
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cs The subprocess is continued with signal s^ see 
signal (2). If address is given then the 
subprocess is continued at this address. If no 
signal is specified then the signal that caused 
the subprocess to stop is sent. Breakpoint 
skipping is the same as for r. 

ss^ As for c except that the subprocess is single 
stepped count times. If there is no current 
subprocess then objfil is run as a subprocess as 
for r. In this case no signal can be sent; the 
remainder of the line is treated as arguments to 
the subprocess. 

k The current subprocess, if any, is terminated. 

VARIABLES 

Adb provides a number of variables• Named variables are set 
initially by adb but are not used subsequently. Numbered 
variables are reserved for communication as follows. 

0 The last value printed. 

1 The last offset part of an instruction source. 

2 The previous value of variable 1• 

On entry the following are set from the system header in the 
corfil . If corfil does not appear to be a core file then 
these values are set from objfil . 

b The base address of the data segment, 

d The data segment size, 

e The entry point. 

m The 'magic' number (0405, 0407, 0410 or 0411). 
s The stack segment size, 

t The text segment size. 

ADDRESSES 

The address in a file associated with a written address is 
determined by a mapping associated with that file. Each 
mapping is represented by two triples (bl, el , f1 ) and (b2, 
e2 , f2 ) and the file address corresponding to a written 
address is calculated as follows. 

bl<address<el => file address=address+f1 -bl, otherwise, 

b2<address<e2 => file address=address+f2- b2, 

otherwise, the requested address is not legal. In some 
cases (e.g. for programs with separated I and D space) the 
two segments for a file may overlap. If a ? or / is 
followed by an * then only the second triple is u^d. 
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The initial setting of both mappings is suitable for normal 
a.out and core files. If either file is not of the kind 
expected then, for that file, ^bl is set to 0, el is set to 
the maximum file size and _fl is set to 0; in this way the 
whole file can be examined with no address translation. 

So that adb may be used on large files all appropriate 
values are kept as signed 32 bit integers. 

FILES 

/dev/mem 

/dev/swap 

a.out 

core 


SEE ALSO 

ptrace(2), a.out(5), core(5) 


DIAGNOSTICS 

'Adb' when there is no current command or format. Comments 
about inaccessible files, syntax errors, abnormal 
termination of commands, etc. Exit status is 0, unless last 
command failed or returned nonzero status. 


BUGS 

A breakpoint set at the entry point is not effective on 
initial entry to the program. 

When single stepping, system calls do not count as an 
executed instruction. 

Local variables whose names are the same as an external 
variable may foul up the accessing of the external. 


EXAMPLES 

After a core 

adb prog 

$r 

$c 

$C 

$e 

bufp/X 

*bufp/X 

write?i 

(cr) 

: b 

:r hello <inp 
main,-l?ia 
data/4X2d 
(cr) 

#100>d0 

<dl=X 

*(<a6+8)/XXX 
write?l #4e75 


dump: 


(second parameter core is assumed) 

(print registers) 

(print C stack trace) 

(print full C stack trace) 

(print external variables) 

(print contents of 'bufp as long hex) 

(print 4 bytes hex where bufp points to) 

(prints first instruction, link a6,... ) 

(print next instruction) 

(set breakpoint at this instruction) 

(run prog with param hello and input from inp) 
(disassemble program starting at main) 

(print data: 4 long hex, 2 short decimal) 

(print next data in same format 
(write #100 to register dO) 

(print dl long hex) 

(print first three longs of parameter area) 
(search for rts instruction at end of proc write) 
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:b (set breakpoint at this address) 

:c (continue program until stop or breakpoint) 

; s (single step through program 

etc. 

On the 68000, as opposed to the 68010 or 68020, the stack 
will not necessarily grow automatically. You can recognize a 
stackoverflow with the following commands: 

adb prog 

$r 

$m 

If the value of register ac is less than the value b2 for 
the second (/) map, the stack overflowed. To get the needed 
stack size, type 

#f00000-<ac=D 

This will output the difference between the top of the stack 
and the access address in decimal. Round the value up some 
kbyte, and give the command 

stksiz prog <value> 
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CADMUS Testmonitor VI.2 Benutzeranleitung 

Rudolf Yfildgruber 

PCS Gmbh 
Pfalzer-Wald-Str. 36 
8000 MGnchen 90 


ABSTRACT 

Der CADMUS Testmonitor VI.2 ist ein Standalone-Programm, 
das vom Minitor von Platte, Floppy-Disk, Band oder Streamer 
geladen werden kann. Es dient als Steuerprogramm zur 
Parametrierung und zum Ablauf einzelner Test- und Diag- 
noseprogramme. Der Testmonitor realisiert eine einheitliche 
Schnittstelle zu den Test- und Diagnoseprogrammen. Fur die 
Bedienerschnittstelle werden MUNDC-Standards verwendet. 

Die Version 1.2 unterscheidet sich von Version 1.0 in folgenden 
Erweiterungen: 

O Laden der Testprogramme von Magnetband oder Streamer 
moglich (sowohl TMU- als auch TSll -Bander werden 
unterstiitzt) 

O Kommandoprozeduren 

O Test der Checksumme beim Laden der Testprogramme 
O Unterstvitzung der SLS48/88 - Konsole 
O weitere Testprogramme verfugbar 
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CADMUS Testroonitor Vl.2 Benutzeranleitung 

Rudolf Wildgruber 

PCS Gmbh 
Pfalzer-Wald-Str. 36 
8000 Munchen 90 


1. Einfuhrung 

Der Testmonitor gliedert sich in 4 Teile: 

O Ablaufsteuerung 
O Kommando-Interpreter 
O Testmonitor-Kommandos 

O Systemfunktionen fur E/A, Filesystem-Zugriff u.a. 

Die Test- und Diagnoseprogramme sind selbstandige Programme, die vom 
Testmonitor geladen und ausgefuhrt werden. 

1.1. Ablaufsteuerung 

— Initialisierungsdialog 
— Aufruf des Kommandointerpreters 

1.2. Kommando-Interpreter 

— Entgegennahme von Benutzereingaben 

— syntaktische Korrektheitsprvifung der Benutzereingaben 

- Plausibilitatsprufung von Flag-Kombinationen bei Aufrufen von Test- 
programmen 

— Ausfiihrung von Kommandos 
— Ausfiihrung von Kommandoprozeduren 

- Laden von Testprogrammen, Priifung der Checksumme, Versorgung 
der Programme mit Parametern und Ausfiihrung 

1.3. TestmonitoKommandos 

— UnterstOtzung des Benutzers bei Testabl&ufen 
— Zugang zur MUNIX-Dateihierarchie 

— einfache Dateifunktionen: Statusabfrage, Listing, Dump 

2. BenutzerschnittsteUe 
2.1. Start 

Der Testmonitor wird vom Minitor von einem Datentrager (Platte, Floppy-Disk, 
Band Oder Streamer) geladen. Der Minitor kann von Band oder Streamer nur 
jeweils die erste Datei (a.out-Format, kein cpio- oder tar-Format) laden. Beim 
Laden von Platte ist folgendes'zu beachten: 

Der Minitor sieht die Filestruktur auf der Platte so, wie sie tatsachlich 
aufgebaut ist. Daher kann der Dateibaum, wenn die Directory-Struktur 
geandert wurde - wie z.B. bei der Newcastle-Connection der Fall, - etwas 
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anders ausehen, wie unter MUNDC. Beim Laden des Testmonitors muss 
diese Tatsache beriicksichtigt werden, und jeweils der vollstandige Pfad- 
namen angegeben werden ( z.B. /nodename/satest ). 

Mit gO wird der Testmonitor wie jedes andere Standalone-Programm gestar- 
tet. 

Beispiele (Benutzereingaben sind fett gedruckt): 

Laden des Testmonitors testmon (im Directory /satest) vom Default- 
Device: 

. / sate st / testmon 

gO 

Laden des Testmonitors testmon vom Streamer 
.rs 

./testmon 

gO 

2.2. Initialisierunsdialog 

Nach dem Starten des Testmonitors wird ein kleiner Initialisierungsdialog mit 
dem Benutzer gefiihrt. 

Dabei wird gefragt nach dem Eingabemedium und Directory, von dem aus die 
Testprogramme geladen werden sollen, ob ein Drucker am System angeschlos- 
sen ist und nach dem Terminal-Typ. 

Nach dem Initialisierungs-Dialog befindet sich der Testmonitor im Kommando- 
Modus (sichtbar am Prompt ’©’) und ist bereit Kommandos, Aufrufe von Kom- 
mandoprozeduren oder Testprogramm-Aufrufe mit oder ohne Parameter- 
Angaben zu akzeptieren. 

2.2.1. Eingabemedium 

Testprogramme und Kommandoprozeduren konnen von Platte, Magnetband 
oder Streamer-Kassette geladen werden. Auf Platte wird eine MUNDC- 
Filesystem-Struktur mit 512 Byte Blockgrosse vorausgesetzt (Achtung: Test- 
programme konnen nicht von Filesystemen mit 1 kByte Blockgrosse geladen 
werden). Auf Band oder Streamer-Kassette miissen die Testprogramme und 
Kommandoprozeduren im cpio-Format abgespeichert sein. 

Das Eingabemedium ist in der Form 
devname(drive.offset) 

zu spezifizieren. Dabei gibt devname den Device-Typ an. Zulassige 
Bezeichnungen fur Gerate sind der nachfolgenden Tabelle zu entnehmen. 
Drive ist die Nummer des Laufwerks und die Bedeutung von offset ist bei Mag¬ 
netband und Streamer gegeniiber Platte und Floppy-Disk unterschiedlich. Bei 
Bandem spezifiziert offset die Anzahl der Files, die auf dem Band iiberlesen 
werden sollen. Bei Platten ist offset die logische Blocknummer, ab der gelesen 
wird. 
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devname 

Device-Tvo • 

rm 

RM02/03/05 (80 MB Fujitsu mit DATARAM controller) 

rl 

RL01/02 

hk 

RK06/07 (80 MB Fujitsu mit EMULEX controller) 

rp 

RP03 

hp 

RP04/05/06, RM02/03 (ohne bad sector handling) 

rk 

RK05 

rx 

RX02 Floppy Disk 

tm 

TM11 Magnetband 

ts 

TS11 Magnetband 

ot 

Tandon Winchester und Floppy (OMTI controller) 

td 

Tandon Winchester (XEBEC controller) 

St 

SCTl 1 Streamer 


Bei rx gibt es eine Besonderheit beziiglich der Laufwerksnummer: 0 und 1 
beziehen sich auf single density Laufwerke 0 und 1; 2 und 3 beziehen sich auf 
double density Laufwerke 0 und 1. 

2.2.2. Directory 

Nach einem current directory wird nur bei Platten als Eingabemedium 
gefragt. Der Directory-Name ist so anzugeben, wie er der tatsachlichen 
Dateistruktur auf dem Eingabemedium entspricht, also ohne Mount-Prafixe 
und eventuell mit dem Knotennamen (bei der Newcastle Connection). 

2.2.3. Drucker 

Die Frage nach einem angeschlossenen Drucker ist mit n (kein Drucker), s 
(serieller Drucker) oder p (paralleler Drucker) zu beantworten. Bei einem 
seriellen Drucker wird zusatzlich nach der Kanalnummer gefragt. 

Einige Testprogramme unterstutzen nur einen Drucker mit paralleler 
Schnittstelle. Siehe dazu Abschnitt BUGS bei den Kurzbeschreibungen der 
Testprogramme. 

2.2.4. Terminal-Typ 

Hier kann der Typ des Konsol-Terminals als String (max. 11 Zeichen) eingege- 
ben werden. Diese Angabe wird von manchen Testprogrammen zur 
Bildschirmsteuerung ausgewertet. Sinnvolle Eingaben sind vtlOO, vt52 oder 
tvi970, d.h. nur bei diesen Terminals kann eine entsprechende Bildschirm- 
maske generiert werden. Bei leerer Eingabe wird dummy als Terminal-Typ 
eingesetzt. 

Einige Testprogramme unterstutzen nur V7700-kompatible Terminals. Siehe 
dazu Abschnitt BUGS bei den Kurzbeschreibungen der Testprogramme. 

2.3. Kommandointerpreter 

Die im Testmonitor zur Verfugung stehenden Kommandos sind an die Shell- 
Kommandos von MUNIX angelehnt. Sie werden nachfolgend ausfuhrlicher 
spezifiziert. 

2.3.1. Kommandos 

In der Testmonitor-Version V 1.2 stehen folgende Kommandos zur Verfugung: 

Is [-1] Inhalt des current directory auflisten. Es werden nur die Datei- 
namen ausgegeben. 

Option: -1 (ausfuhrliches Listing mit Dateigrosse in Bytes und 
Berechtigungsbits) 
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cat file Ausgabe der Datei file auf Konsole 

pr file Ausgabe der Datei file auf Drucker 

exit Beenden Testmonitor 

help Ausgabe eines Help-Textes auf Konsole 

xdfile Ausgabe der Datei file auf Konsole im 'hex-dump’-Format 

cd directory 

Wechsel des current directory, jedoch im Gegensatz zu MUNDC 
nur relativ zum current directory. Absolute Directory-Namen 
werden nicht akzeptiert. cd erkennt auch als Directory- 
Namen, jedoch nur den unmittelbaren Vater; ein Wechsel zu 
weiter oben liegenden Knoten ist nur durch mehrmaligen 
Eingabe von 'cd zu erreichen. 

cdev dev [dir] 

Wechsel des Eingabemediums mit Angabe eines Directories bei 
Platten 

cterm type 

Terminal-Typ andem, z.B. zur Korrektur; als neuer Terminal-Typ 
wird type eingetragen 

pwd Ausgabe des current directory, es wird jeweils der komplette 
Pfadnamen mit Device angegeben; die root wird dabei mit V 
bezeichnet. 
prog [param-list] 

Aufruf des Testprogrammsprogr: 

Laden der Datei prog vom Eingabemedium und current directory 
Priifung der Checksumme 

Versorgung von prog mit den angegebenen Parametern 
Start von prog 

proc [param-list ] 

Aufruf der Kommandoprozedur proc: 

Laden der Datei proc vom Eingabemedium und current directory 
Interpretation des Dateiinhalts als Testmonitor-Kommandos 
Angegebene Paramter werden ignoriert, Innerhalb einer Kom¬ 
mandoprozedur konnen weitere Prozeduren aufgerufen werden. 
Die maximale Schachtelungstiefe betragt 10. 

2.3.2. Testprogramm-Parameter 

Die Testprogramme laufen parametergesteuert ab. Es ist zwischen 
allgemeinen und speziellen Parametern zu unterscheiden. Allgemeine Param¬ 
eter sind solche, die fur alle oder nahezu alle Testprogramme sinnvoll und 
anwendbar sind. Spezielle Parameter sind einem einzigen oder sehr wenigen 
Testprogrammen zugeordnet. 

Allgemeine Parameter werden als Teil des Kommandos beim Start eines Test- 
programmes angegeben. Der Testmonitor baut einen Parameterblock auf und 
iibergibt diesen an das Testprogramm. Fur nicht angegebene Parameter wer¬ 
den Default-Werte verwendet, die abhangig vom Testprogramm sind. Ein 
allgemeiner Parameter (dialog) gibt an, ob fQr die speziellen Parameter 
Default-Werte verwendet werden oder ob das Testprogramm mit dem Bediener 
einen Dialog fuhren soli. 

Allgemeine Parameter sind: 
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pass Anzahl no der Testdurchl&ufe (0 fur Dauertest), wie beim 
Testprogramm-Aufruf mit pass=no angegeben. 0 steht fur 
Dauertest. 1 ist der Default-Wert, wenn beim Aufruf keine 
Angabe gemacht wurde. 

test Liste der Teiltests, die durchgefuhrt werden. 

unit Liste der Units (Testeinheiten: z.B. drives oder controllers), die 
getestet werden. 

flag Angabe von speziellen Flags zum Verhalten des Testprogramms 
im Fehlerfall. Die Flags sind: 

HOE halt on error 

Testprogramm anhalten und Ruckkehr in den Komman- 
domodus 

LOE loop on error 

In einer unendlichen Schleife den Fehler reproduzieren 
IER inhibit error reports 

Kein Ausdruck einer Fehlermeldung 
1XE inhibit extended error reports 

Kein Ausdruck einer ausfvihrlichen Fehlermeldung, nur 
kurze Fehlermeldung 

PRI print on line printer 

Ausdruck der Fehlermeldungen auf Drucker 
BOE bell on error 

Akustisches Signal im Fehlerfall 
ISR inhibit statistical reports 

Keine Fehlerstatistik nach einem Testdurchlauf 

Die entsprechenden Flags sind gesetzt, wenn sie beim 
Testprogramm-Aufruf mit flag-... angegeben wurden. Per 
default wird kein Flag gesetzt. 

base Basis-Gerateadresse addr, die beim Aufruf mit 6ase=addr 
angegeben wurde, sonst 0. 

vec Interrupt-Vektor Adresse addr, die beim Aufruf mit vec=addr 
angegeben wurde, sonst 0. 

dialog Das Testprogramm fragt spezielle Parameter im Dialog ab. 

si Die Zeichenfolge string (max. 11 Zeichen), die beim Aufruf mit 

sl=string angegben wurde, sonst leer. Die Bedeutung dieses 
Parameters legt das Testprogramm fest. 


Die allgemeinen Parameter werden beim Aufruf in param-list angegeben. Die 
Syntax fur param-list ist dabei folgendermassen definiert: 

param-list param [param]... 

param pass=no | test=no-fisf | \mit=no-list \ tlag=flag-list | 

base=no | vec=no | dialog | sl=string 
. no-list (nofran^e) [ , (no\range)] ... 


range 

flag-list 

.no 


no—no 

flagname [ ,fl agname] ... 

eine positive ganze Zahl (einschliesslich 0) oder eine Hexa- 
dezimalzahl in der Form 0xnnnnnn 
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flagname eines der oben spezifizierten Flags 

string eine beliebige Zeichenfolge (maximal 11 Zeichen) 

2.3.3. Koramandoprozeduren 

Kommandoprozeduren fur den automatischen Ablauf von Testprogrammen 
konnen nur unter MUNDC erstellt werden. Jede Zeile der Kommandoprozedur 
darf hochstens ein Testmonitor-Kommando, einen Testprogramm-Aufruf oder 
einen Kommandoprozedur-Aufruf enthalten. Leerzeilen sind erlaubt, Kom- 
mentare verboten. 

Die Abarbeitung einer Zeile der Kommandoprozedur wird protokolliert. 

2.4. Terminalhandling 

Fur die Terminalein- und ausgabe stehen nachfolgend beschriebene Steuer- 
zeichen zur Verfugung: 

CTRL S: Anhalten einer gerade laufenden Terminal-Ausgabe. 

CTRL Q: Fortsetzen einer mit CTRL S angehaltenen Terminal-Ausgabe. 
CTRLX: Loschen der aktuellen Eingabezeile im Kommandomodus. 

CTRLC: Unterbrechen eines gerade laufenden Programmes. 

3. Beispiele 

Anhand des Testprogrammes check soil ein kompletter Dialog durchgespielt 
werden: 

Dabei werden die Ausgaben des Testmonitors fett gedruckt dargestellt, 
sowie die Eingaben des Benutzers in Kursiv- Schrift. 

Es wird angenommen, dass sowohl der Testmonitor wie auch die Testpro- 
gramme bereits unter MUNDC in das Directory /satest im Filesystem 
/dev/hkO eingespielt worden sind, und die Directory-Struktur 
• unverandert (also keine Superroot der Newcastle Connection) vorliegt. 

Nach dem Einschalten des Systems bzw dem Betatigen des INIT- 
Schalters erscheint an der Konsole 

MINITOR 

Mit der Eingabe 
/satest/testmon 

wird der Testmonitor von Platte (80 MB Fujitsu, Laufwerk 0) geladen und 
es meldet sich wieder der Minitor mit dem Prompt V . 

Mit 

go 

wird der Testmonitor nun gestartet. Er meldet sich mit dem Text: 
CADMUS-TESTMONITOR Vl.2 
input-device xx(d.o): 

Nach Eingabe des Eingabemediums, (z.B. rx(2,0) fur das erste Floppy- 
laufwerk) oder im Beispiel fur die Platte 

hk(0,0) 

fragt der Testmonitor weiter: 
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directory : 

Die Eingabe 
/safest 

stellt das current directory ein. 

Der weitere Dialog: 

line printer (n/s/p): s 

line number (1-7): 1 

terminal ivtlOO 
@ 

Nun ist der Testmonitor bereit, Kommandos oder Programmnamen zu 
akzeptieren, im Beispiel: 

check sl=hk-w unit-1 flag-PRI.IXE 

Alle weiteren Ausgaben erscheinen am Drucker, bis sich der Testmonitor 
wieder mit @ zuruckmeldet. 

Ein weiteres Beispiel ist der Aufruf des SCSI-Testprogramms scsitsL 
Das Kommando 

©scsitst pass=3 test =1,3-6 unit=0,l sl=d503 
fuhrt zu folgendem Testablauf: 

Die Tests mit den Nummem 1,3,4,5 und 6 werden in dieser Reihen- 
folge ausgefuhrt. Dieser Testdurchlauf erfolgt insgesamt dreimal. 
Getestet werden unit 0 und unit 1, d.h. 2 Winchester-Drives. Die Win¬ 
chester sind vom Typ TM 503. Es wird der Controller DTC 520 verwen- 
det. 

4. I/O Page Adressen 

Fur Konsole und seriellen Drucker wird sowohl eine DLVll als auch eine 
SLS48/88-Schnittstelle unterstvitzt. 

In der Version 1.2 sind die Adressen und Interruptvektoren von Konsole und 
Drucker fest eingestellt und konnen auch nicht durch die Parameter base 
und vec verandert werden. 

Die in Vl.2 gultigen Adressen und Interrupt-Vektoren sind nachfolgend 
angegeben. Beachten Sie bitte: 

— die oktal angegebenen Adressen sind direkt auf die Controller-Switches zu 
iibertragen; 

— die sedezimal angegebenen Adressen in Klammern stellen die echten 
Adressen im 68000-Adressraum dar und sind bei den Interruptvektoren das 
Vierfache der oktal angegebenen Adresse. 


d 
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Gerat 

Interruptvektor 

1/0-Page Adresse 


oktal 

hex 

oktal 

hex 

DLVl 1-Konsole 

60 

CO 

777560 

FFFF70 

paralleler Drucker 
serieller Drucker: 

200 

200 

777514 

FFFF4C 

DLVl 1-line 1 

300 

300 

776500 

FFFD40 

DLVl 1-line 2 

310 

320 

776510 

FFFD48 

DLVl 1-line 3 

320 

340 

776520 

FFFD50 

DLVl 1-line 4 

330 

360 

776530 

FFFD58 

DLVl 1-line 5 

340 

380 

776540 

FFFD60 

DLVl 1-line 6 

350 

3A0 

776550 

FFFD68 

DLVl 1-line 7 

360 

3C0 

776560 

FFFD70 

SLS48/88 

300 

300 

776000 

FFFC00 


5. Verfugbare Testprogramme und Kommandoprozeduren 


5.1. Testprogramme 

In VI.2 sind nachfolgend aufgefiihrte Testprogramme verfligbar: 


bsctest 

check 

dztst 

fpptst 

Lbptst 

memtst 

muxketst 

qetest 

scsitst 

sLutst 

168030 

t68050 

tdma 


BSC-KE Testprogramm 

Platten-Test- und Formatierprogramm 

DZVll Testprogramm 

Floating Point Processor Test 

CANON Laser Beam Printer Test 

Speichertest 

MUX-KE Testprogramm 

3COM Q-Bus Ethernet Controller Testprogramm 
SCSI-Adapter Test 
SLS48/SLS88 Test 

QU68030/50 Prozessortest (ohne MMU-Stufe 2) 
QU68050 Prozessortest (nur MMU-Stufe 2) 

DMA Testprogramm 


Dabei spielen die Programme memtst und Ibptest eine gesonderte Rolle, da 
diese nach Ablauf nicht mehr in den Testmonitor zuriickkommen. Der Test- 
monitor muss danach mit dem Minitor neu geladen und gestartet werden. 

Fur qetest wird ein MUNIX-Programm (kein Standalone-Programm) echoserver 
mitgeliefert, das von einem anderen CADMUS- System mit qetest kommun- 
iziert. 

5.2. Kommandoprozeduren 

In VI.2 werden standardmassig 4 Kommandoprozeduren ausgeliefert 
(emuinit , emuinitpr, emuinit2, emuinit2pr). Sie dienen zur Initialisierung 
(Formatierung und Bad Sector Test) von Platten, die an den EMULEX SC02 
Controller (RK06/07-Emulation) angeschlossen werden. 

6. Installation 

Der . Testmonitor ist mit den Testprogrammen Bestandteil der MUNDC- 
Basissoftware (ab VI.5). Im MUNIX-Dateibaum ist er im Directory /satest oder 
/usr/satest zu finden. 

Separat erfolgt die Lieferung des Testmonitors Vl.2 mit den erwahnten Pro- 
grammen auf Band, Streamer-Kassette oder Floppy-Disk: 
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Die Floppy ist im MUNDC-Filesystem-Format beschrieben (512 Byte 
Blockgrosse). Das Magnetband bzw. die Streamer-Kassette enthalt als 
erste Datei den Testmonitor im a.out-Format und als zweite Datei die 
Testprogramme und Kommandoprozeduren im cpio-Format. Der Test- 
monitor kann also direkt von diesen Datentragern geladen werden. Um 
die Testprogramme vom Testmonitor zu laden, ist dann als Einga- 
bemedium rx(2,0), tm(0,l) oder st(0,l) einzugeben. 

Wir empfehlen, die Programme auch unter die Root einzulesen, damit sie 
direkt von der Winchester geladen werden konnen. Folgende Kommandos 
sind z.B. notwendig, um die Streamer-Kassette einzulesen: 

cd / 

ink dir sates! 
cd satest 
stskip 1 

cpio -ivmS < /dev/nrstO (Standalone-Testprogramme) 
cd / 

cpio -ivmS < /dev/rstO (Echoserver) 
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MUNIX (STANDALONE-TEST) 


BSCTEST(TM) 


NAME 

bsctest - KE-BSCl/2 (KE-SIOl + KE-V24 / KE-SI02 ) - test 
SYNOPSIS 

bsctest [param-list] 

DESCRIPTION 

Bsctest checks 4 (2) synchronous BSC channels in short circuit mode 
(short circuit plug K907.027: 

channel 0 < - > channel 1 
channel 2 < - > channel 3). 

Data and control lines are checked in both directions. 

Hardware: KE-BSC2 or KE-BSCl or CP-WCS 

+KE-SI02 +KE-SI01 [KE-SIOl] +KE-SI02 

+KE-V24 [KE-V24] 

(default: KE-BSC2 

+KE-SI02) 

The jumper configuration for the boards is printed on the console if 
bsctest is started with the parameter dialog . 

PARAM-LIST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

flag HOE Halt on error and return to testmonitor. 

BOE Bell on error. 

LOE Loop on error. Number of test passes is set to 0 (infinite test 
loop). 

unit Number of channels (2 or 4). Default is 4 . 

dialog The test program asks interactively for test commands. Jumper 
configurations are printed according to hardware configurations. 

EXAMPLES 

Test with 10 passes, halt on error and bell on error, 2 channels 
bsctest pass=10 flag=HOE.BOE unit=2 

FILES 

KEBSC2.KEA 

KEBSC2.MAP 

SEE ALSO 

T920.518 MUNIX RJE mit BSC-KE-Controller 
T922.103/104/105.01 KE-SI02 Testvorschrift 
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CHECK(TM) 


MUNDC (STANDALONE-TEST) 


CHECK(TM) 


NAME 

check — disk checking and formatting 
SYNOPSIS 

check sl=devname[-(wlu)] [param-list] 

DESCRIPTION 

Check is the CADMUS disk checking program. Additionally it has a for¬ 
matting capability for disks with standard headers. 5 1/4" winchesters 
emulated by the Andromeda WDCll controller as RL02 can also be for¬ 
matted. As disk checking is done without interrupts a separate test for 
controller interrupts was added. 

The main purpose of check is to test disks for the location of bad sectors 
and to write the bad sector file onto disks. The bad sector file is a list of 
all bad sectors found on a disk. MUNDC uses this information to avoid 
allocating bad sectors to a user's file. If there is an error in a header, or 
if there is a read or write error within one sector, that sector is defined 
as a bad sector. If possible the header of this sector is marked. 

Check is aborted if one of the following conditions occurs: 

- controller not accessible at specified or default address 

- bad status on all specified or default units 

- too many bad blocks (more than 126) on a tested unit 

If there is a bad status on one unit, that unit is omitted from testing. 

A brief explanation of check is available in check.help . Use the testmoni- 
tor cat command to get it on screen. 

PARAM-LIST 

si The device name (see table below) of the disks to be tested 
optionally followed by —w or —u . 

The devices in the following table are supported by check. The 
listed CSR and vector addresses (hex notation) are default values. 
They can be changed by the base resp. vec parameter. Devices 
indicated by STD in the column Formatting uses standard 
headers. Those indicated by WDCll need the ANDROMEDA WDCll 
controller to be formatted. 


Supported Devices 


Device 

Name 

Disk 

Type 

CSR 

Address 

Vector 

Address 

Formatting 

hk 

RK06/07 

FFFF20 

220 

STD 

rl 

RL01/02 

FFF900 

ICO 

WDCll 

hi 

RL01/02 

FFF910 

1D0 

WDCll 

rm 

RM02/03/05 

FFFDCO 

2B0 

STD 


The option -w opens the disk in read/write-mode, while -u opens 
the disk in update-mode. A missing option opens the disk in read¬ 
only-mode. 

In read/write-mode the contents of the disk is overwritten, bad 
sectors are marked, the bad sector file is initialized or modified 
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CHECK(TM) 


MUNIX (STANDALONE-TEST) 


CHECK(TU) 


and formatting is possible. This is the proper mode for new disks. 
In update-mode sectors ar tested only by reading, bad sectors are 
marked and the bad sector file is initialized or modified. Format¬ 
ting is inhibited. 

In read-only-mode the contents of the disk is left unchanged. 
Sectors are tested only by reading, no formatting is done, no sec¬ 
tor is marked as bad and the contents of an existing bad sector 
file is not modified. 

For example (user input is bold ): 

sl=hk-w or 
sl=rm-u or 
sl=rl 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 0 to 6 . If no test-list is 
specified, tests 0, 1, 2 and 6 are executed by default. During a 
test pass the tests are executed in increasing order. The test 
descriptions refer to disks opened in read /write-mode. If you 
opened a disk in another mode read the descriptions accordingly: 

0 Bad Sector Scan: 

The complete disk is tested. Sectors are first written in 
increasing order and then read in decreasing order. A bad 
sector file is written onto the disk. 

1 Sector Range Test: 

A range of consecutive sectors is tested. By default these 
are the sectors 0 to 1999 . If the parameter dialog is 
specified you are interactively asked for the starting sec¬ 
tor and the number of sectors to be tested. The sectors 
are tested alternately: 1st sector, last sector, 2nd sector, ... 
to the midst of the given interval. The already existing bad 
sector file is updated. 

2 Random Sector Test: 

Test disk sectors in random order. By default 2500 sectors 
are tested. If the parameter dialog is specified you are 
interactively asked for the number of sectors to be tested. 
The already existing bad sector file is updated. 

3 Inspect Bad Sector File: 

List the contents of an existing bad sector file. 

4 Append Bad Sectors: 

Bad sectors are appended manually to an existing bad 
sector file. When the message enter sector numbers (-1 to 
end) appears on the screen, type in the numbers of sec¬ 
tors to be marked as bad sectors. To exit from this test 
enter —1 . 

This test is extremely helpful if you know any bad sectors 
not detected by the check program. 
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CHECK(TM) 


MUNIX (STANDALONE-TEST) CHECK(TM) 


5 Format Disk: 

Write good sector headers and initialize data fields option¬ 
ally on the complete disk volume or on single tracks. If 
the parameter dialog is not specified the complete disk is 
formatted. If dialog is specified you are interactively 
asked for complete or single track formatting. 

6 Controller Interrupt Test: 

A RESET or DRIVE CLEAR command is executed with inter¬ 
rupt enabled. The test is successful if the controller inter¬ 
rupts within a certain time (about 1 second). There are 
three kinds of possible error conditions: 

— timeout: no interrupt occured 

— spurious interrupt: daisy chain not closed 

— illegal interrupt: wrong interrupt address 

As a proper test strategy for new disks we suggest first to format all 
drives with test 5 and then to start the default tests for all drives. 

If there is a new bad sector on an already used disk test a small range 
around the bad sector by test 1 (dialog specified) or use test 4 to mark 
the bad sector manually. Used disks should be checked in read-only¬ 
mode. 


unit A list of units (disk drive numbers) to be tested. 0 is default. 

For hJc and rm a disk drive number is in the range 0 to 7 , for rl 
and hi the range is 0 to 3 . 

flag A list of flags (see CADMUS Testmonitor Benutzeranleitung). PRI 
makes a line printer protocol. IXE and IER suppress detailed 
error messages. HOE terminates check immediately if there is a 
bad status on one unit or if the controller interrupt test fails. 
BOE bells on an error condition. All other flags are ignored 

base A nonstandard CSR address 

vec A nonstandard interrupt vector address. 

dialog Ask interactively for special parameters. Applies to tests 1, 2 and 
5. 


EXAMPLES 

Formatting a complete 80 MB Fujitsu winchester (EMULEX controller): 

check sl=hk-w unit=0-2 test=5 
Default tests with line printer protocol: 
check sl=hk-w unit=0-2 flag=PRI 

Formatting a complete 80 MB Fujitsu winchester (DATARAM controller): 
check sl=rm-w test=5 

Testing a user defined sector range in read-only-mode 
check sl=rl test=l unit=l dialog flag=PRI 

FILES 

check.help 
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CHECK(TM) 


MUNIX (STANDALONE-TEST) 


CHECK(TM) 


SEE ALSO 

rl(4), rm(4), hk(4), iopage(7) 

Bad Sector Handling 

CADMUS Testmonitor Benutzeranleitung 

BUGS 

The interrupt test doesn't work with DATARAM S04/A controller. Ignore 
the timeout message. 
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DZTST(TU) 


MUNIX (STANDALONE-TEST) 


DZTST(TM) 


NAUE 

dztst — DZVll test (without send interrupts) 

SYNOPSIS 

dztst [param-list] 

DESCRIPTION 

Dztst is the CADMUS DZVll test program. 

Dztst tests simultanously two DZVll channels. One acts as the 
transmitter the other as the receiver. In this way all DZVll channels can 
be tested. 

In test 1 data is only transmitted, while test 2 transmits and receives 
data using two channels. Test 3 checks the signals: DTR.RING LINE and 
CARRIER LINE. For the tests 2,3 you need a short circuit plug, connect¬ 
ing the channels 0 and 1,2 and 3 etc. 

PARAM-LIST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 1 to 3 . If no test-list is 
specified, tests 1 to 3 are executed by default. During a test pass 
the tests are executed in increasing order. 

1 Transmit test: 

The output channel is tested (255 characters will be 
transmitted). 

2 Transmit - receive test: 

The output and the input channels will be tested (255 
characters are transmitted from output to input channel). 

3 Modem test: 

The signals: DTR, CARRIER LINE and RING LINE will be 
tested. 

unit Input and output channels. All are default. 

flag A list of flags (see CADMUS Testmonitor Benutzeranleitung). PRI 
makes a line printer protocol. IER suppresses error messages. 
BOE bells on error. HOE halts on error. LOE loops on error. 

base This parameter is ignored. 

vec This parameter is ignored. 

dialog If specified you are interactively asked for the number of charac¬ 
ters to be transferred, the channels to be tested and display 
flags. 


EXAMPLES 

Default tests (1,2,3); Channels: All (001,203,..) ; 255 characters, 
dztst 

Default tests with dialog 
dztst dialog 
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DZTST(TM) 


MUNIX (STANDALONE-TEST) 


DZTST(TU) 


Only test 1; output channel 2 ; 255 characters, 
dztst test= 1 unit=2 

Only test 2; channel 3 and 5; loop on error; bell on error 
dztst test=2 unit=3,5 flag=LOE,BOE 

SEE ALSO 

Beschreibung fuer DZVll - Testprogramm 
CADMUS Testmonitor Benutzeranleitung 
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EHUINIT(TM) 


HUNDC (STANDALONE-TEST) 


EHUINIT(TU) 


NAME 

emuinit - format and check an 84 MB Fujitsu drive with EMULEX SC02 
controller 

SYNOPSIS 

emuinit 

emuinitpr 

emuinit2 

emuinit2pr 

DESCRIPTION 

These command procedures format and check complete 84 MB Fujitsu 
drives with EMULEX SC02 controller. They can be used for the initial set¬ 
up of winchester drives. 

Emuinit and emuinitpr refer to the first drive, while emuinit2 and 
emuinit2pr refer to the second drive. Emuinitpr and emuinit2pr make a 
line printer protocol, while emuinit and emuinitS only print a protocol to 
the console. 

PARAM-UST 

All params are ignored. 

SEE ALSO 

check(TM) 

Bad Sector Handling 

CADMUS Testmonitor Benutzeranleitung 


> 
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FPPTST(TM) 


MUNIX (STANDALONE-TEST) 


FPPTST(TM) 


NAME 

fpptst — test program for FPP 81 (floating point processor) 

SYNOPSIS 

fpptst [param-list] 

DESCRIPTION 

Fpptst serves as a GO/NOGO test program for the floating point proces¬ 
sor FPP 81. Both single loop tests and infinite loop tests are possible. For 
a detailed description of fpptst see FPP 81 Floating Point Prozessor Tes- 
tanweisung. 

PARAM-UST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 1 to 30. If no test-list is 
specified, all tests are executed by default. During a test pass the 
tests are executed in increasing order. 

1..19, 21.22 

Instruction tests: all floating point instructions are tested 
(single precision only) with different address modes. 

20 Compare (CMP) / CSR-TEST 

23-27 Address mode tests 

28 Trap test 

29 Double precision test 

30 Op. buffer - result buffer - transfer test 

unit This parameter is ignored. 

flag A list of flags (see CADMUS Testmonitor Benutzeranleitung). PRI 
makes a line printer protocoil. IER suppresses error messages. 
BOE bells on error. HOE halts on error. LOE loops on error. 

base This parameter is ignored. 

vec This parameter is ignored. 

si This parameter is ignored. 

dialog The test program asks interactively for test commands. 

SEE ALSO 

FPP 81 Floating Point Prozessor Testanweisung 
CADMUS Testmonitor Benutzeranleitung 
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LBPTST(TM) 


MUNIX (STANDALONE-TEST) 


LBPTST(TM) 


NAME 

lbptst — laser beam printer test 

SYNOPSIS 

lbptst 

DESCRIPTION 

Lbptst is the test program for the CANON laser beam printer. Lbptst 
overwrites the testmonitor in main memory. After termination of lbptst 
the testmonitor has to be loaded from disk, tape or streamer by the Min- 
itor. 

PARAM-LIST 

All params are ignored. Lbptst asks the user for test commands. 

SEE ALSO 

Minitor-Manual 

CADMUS Testmonitor Benutzeranleitung 
LBP68000 LASER PRINTER SYSTEM - Testanweisung 

BUGS 

The console is dead when the LBP controller is missing. Push INIT. 
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MUNIX (STANDALONE-TEST) 


MEMTST(TM) 


NAME 

memtst — memory test 

SYNOPSIS 

memtst 

DESCRIPTION 

Memtst is the CADMUS memory test program. Memtst overwrites the test- 
monitor in main memory. After termination of memtst the testmonitor 
has to be loaded from disk, tape or streamer by the Minitor. 

PARAM-UST 

All params are ignored. Memtst asks the user for test commands. 

SEE ALSO 

Minitor-Manual 

CADMUS Testmonitor Benutzeranleitung 
Beschreibung fuer Speichertestprogramm MEMTST 

BUGS 

Memtst supports only a parallel line printer. 
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MUNIX (STANDALONE-TEST) 


MUXKETST(TM) 


NAME 

muxketst — MUX-KE test (without interrupt handling) 

SYNOPSIS 

muxketst [param-list] _ 

DESCRIPTION 

Muxketst is the CADMUS MUX-KE test program. 

Muxketst tests simultanously two MUX-KE channels (DH). One acts as the 
transmitter the other as the receiver. 

In test 1 data is only transmitted, while test 2 transmits and receives 
data using two channels. For test 2 you need a short circuit plug. 

PARAM-LIST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 1 to 2 . If no test-list is 
specified, tests 1 and 2 are executed by default. During a test 
pass the tests are executed in increasing order. 

1 Transmit test: 

The output channel is tested (255 characters will be 
transmitted). 

2 Transmit - receive test: 

The output and the input channels will be tested (255 
characters are transmitted from output to input channel). 

unit Input and output channel (max. 2 channels). 0 and 1 are default. 

flag A list of flags (see CADMUS Testmonitor Benutzeranleitung). PRI 
makes a line printer protocol. IER suppresses error messages. 
BOE bells on error. HOE halts on error. LOE loops on error. 

base This parameter is ignored. 

yec This parameter is ignored. 

dialog If specified you are interactively asked for the number of charac¬ 
ters to be transferred, the channels to be tested and display 
flags. 


EXAMPLES 

Default tests (1,2); Channels: 0 and 1 ; 255 characters, 
muxketst 

Default tests with dialog 
muxketst dialog 

Only test 1; output channel 2; 255 characters, 
muxketst test=l unit=2 

Only test 2; channel 3 and 5; loop on error; bell on error 
muxketst test=2 unit=3,5 flag=LOE,BOE 
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MUXKETST(TM) 


MUNIX (STANDALONE-TEST) 


MUXKETST ( TM ) 


SEE ALSO 

Beschreibung fuer MUX-KE - Testprogramm 
CADMUS Testmonitor Benutzeranleitung 


March 21, 1984 


Page 2 








QETEST(TH) 


MUNIX (STANDALONE-TEST) 


QETEST(TH) 


NAME 

qetest - test 3 Com QBus Ethemet-Controller QE 
SYNOPSIS 

qetest [param-list] _ 

DESCRIPTION 

qetest is a check and diagnostic program for the 3 Com Ethernet Con¬ 
troller QE. qetest offers several functional tests for the memory, control 
and serial board of the controller. 

Memory and Transmit-functions are testable (with some restrictions) 
without another Ethernet-Controller. The Receive-function-test and test 
of data-integrity at transmission need an echoserver running on a 
remote unix-machine. The echoserver should reside in /usr/bin. 
qetest is aborted if control-registers or buffermemory-addresses are not 
accessible. There is no checking of the interrupt-vector because qetest 
runs in polling-mode. 

After every pass qetest may be forced to detail error-messages. 
PARAM-UST 

dialog In dialog-mode qetest gives detail information before running a 
test. 

pass Number of test passes; 0 for infinite test Coop. The default value 
is 1. An infinite test loop can be stopped with CNTR-C. 

test A list of testnumbers in the range of 0 to 4. If no test-list is 
specified, test 0, 1, 4 are executed by default. Tests are executed 
in increasing order during a test pass. 

0 Test of buffer memory: Addressing, Data and byte- 
operaitions are tested. 

1 Transmit a single packet using each buffer. The test checks 
transmit-done, jam-occurrence and buffer-re lease. No 
echoserver is required. 

2 Transmit multiple packets. All 16 buffers are prepared for 
transmission, then the controller is started. Checking is 
done analogous test 1. 

3 Receive a single packet using each buffer. Each packet on 
the Ethernet is received independent of its destination 
address. (Monitoring Ethernet cable). 

4 Echo-Test: Transmit and Receive of a single packet with 
check of data integrity. 

An echoserver on a remote unix machine is necessary to 
reflect the Ethernet packet. If test 4 is selected, a dialog 
asks the addressing parameters before starting the test- 
passes. 
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QETEST(TM) 


MUNIX (STANDALONE-TEST) 


QETEST(TM) 


flag HOE halt on error. 

LOE loop on error, qetest loops the faulty test independently of 
further errors until break. 

IER, DCE inhibit error reports. Only the error-count of the actual 
pass and the total error-count are displayed. After every error 
report a detained explanation of the error-codes may be asked by 
the user. 

EXAMPLE 

Infinite echo-test: 

qetest test=4 pass=0 

FILES 

/usr/bin/echoserver 
SEE ALSO 

Ethemet-Controller 3C200 
Installation und Standalone-Test 
im System QU68000. 

T923.408.01 


March 21, 1984 


Page 2 









SCSITST(TM) 


MUNDC (STANDALONE-TEST) 


SCSITST(TM) 


NAME 

scsitst— test program for SCSI adapter. 

SYNOPSIS 

scsitst [param-list] 

DESCRIPTION 

Scsitst Version 3.0 tests the SCSI-Bus-Controller and the SCSI-Adapter 
with a 5 1/4" Winchester or a 5 1/4" Floppy. 

PARAM-UST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 0 to 6 . If no test-list is 
specified, test 2 (read sequent) is executed by default. 

0 Read block - you are asked for the number of the block to 
be read. 

1 Write block - you are asked for the number of the block to 
be written. 

2 Read sequent - read the blocks of the data medium (floppy 
or winchester) sequentially. 

3 Write sequent - write blocks sequentially. 

4 Write + read + compare sequent 

5 Write + read + compare zigzag 

6 Write sequent read + write random 

unit Logical drive number (0..3). Unit 0 winchester 0, unit 1 winchester 
1, unit 2 floppy 0. and unit 3 floppy 1. 

si Controller- and drive type. Dor d for DTC 520 controller. O or o 
for OMTI 20D controller. 503 for TM 503 winchester, 603 for TM 
603 winchester, 703 for TM 703 winchester, 100-4 for TM 100-4 or 
TM 101 floppy, 208 for RO 208 winchester, 1065 for Maxtor 1065 
winchester and 6185 for BASF 6185 winchester. For example D503 
for DTC 520 controller and TM 503 winchester. 

dialog The test program asks interactively for test commands. 

EXAMPLES 

Zigzag-test, 1 pass, with DTC 520 controller and TM 503 winchester as 
unit 1. 

scsitst pass=l unit=l sl=D503 test=5 Oder 
scsitst pass=l unit=l sl=d503 test=5 

Interactive testing. 

scsitst dialog 
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SEE ALSO 

Beschreibung fuer SCSI - Testprogramm 
CADMUS Testmonitor Benutzeranleitung 

BUGS 

Scsitst works fine only with a VTlOO-compatible terminal. 
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SLUTST(TM) 


MUNIX (STANDALONE-TEST) 


SLUTST(TM) 


NAME 

slutst — SLS-48 and SLS-88 test program. 

SYNOPSIS 

slutst [param-list] 

DESCRIPTION 

Slutst Version 3.0 tests the serial lines of the Multi-Function-Board 
(MFB). To run this test you need a DLVll for the console interface (stan¬ 
dard Z^C-console). 

PARAM-UST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

dialog The test program asks interactively for test commands. 

EXAMPLES 

Short circuit test with 100 passes 
slutst pass=100 
Interactive testing, 
slutst dialog 

SEE ALSO 

SLS 88 - Testprogramm 

CADMUS Testmonitor Benutzeranleitung 

BUGS 

Slutst works fine only with a VT 100-compatible terminal. 
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T68030(TM) 


MUNDC (STANDALONE-TEST) 


T68030(TM) 


NAME 

t68030 — processor test for QU68030/50 
SYNOPSIS 

t68030 [param-list] 

DESCRIPTION 

T68030 version 3.1 tests the QU68030/50. The program checks for 
MC68000 or MC68010. The second mmu-stage of QU68050 is not tested 
(see T68050(TM) ). 

PARAM-UST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 0 to 10. If no test-list is 
specified, tests 0 .. 7 and 10 are executed by default. During a 
test pass the tests are executed in increasing order. 

0 (ed) test of basic processor functions 

1 (ad) test of address modes. 

2 (bel) test of 1-operand instructions. 

3 (be2) test of 2-operand instructions. 

4 (rr) RAM-ROM test. 

5 (mt) MMU - test. 

6 (sd) test of MMU - segment descriptors 

7 (ir) interrupt test. 

8 is ignored. This test (force parity error) can only be 
started interactively. 

9 (pf) Page-Fault-Test. (Nur QU68050) 

10 (bt) bus timeout test 

flag HOE Halts (program termination) on error and returns to test- 
monitor. PRI prints error messages to line printer. EER 
suppresses extended error messages. 

dialog The test program asks interactively for test commands. - 

EXAMPLES 

Test with extended error messages, do not halt on error. 
t68030 

100 test passes, halt on error and suppress extended error messages. 
t68030 pass=100 flag=HOE,EER 
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MUNDC (STANDALONE-TEST) 


T68030(TM) 


Interactive testing. 

t68030 dialog 


SEE ALSO 

Programmbeschreibung t68030 
CADMUS Testmonitor Benutzeranleitung 

BUGS 

T68030 works fine only with a VTl OO-compatible terminal. Only a parallel 
line printer is supported. 
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T60O5O(TM) 


MUNIX (STANDALONE-TEST) 


T68050(TM) 


NAME 

t68050 — MMU 2 test program 
SYNOPSIS 

t68050 [param-list] 

DESCRIPTION 

T68050 Version 3.0 tests the second MMU-stage of the QU68050. 
PARAM-UST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

EXAMPLES 

Test with 100 passes. 

t68050 pass=100 


SEE ALSO 

Kurzbeschreibung fuer MMU2 - Testprogramm 
CADMUS Testmonitor Benutzeranleitung 

BUGS 

T68050 works fine only with a VT 100-compatible terminal. 
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TDMA(TM) 


MUNIX (STANDALONE-TEST) 


TDHA(TM) 


NAME 

tdma — DMA - test program 

SYNOPSIS 

tdma [param-list] 

DESCRIPTION 

Tdma version 3.0 is running under QU68030 or QU68050 For this test 
you have to plug a test-CP to the CADMUS-System. 

The test-CP is a Communication Processor (in German Kommunikations- 
ELement or KE) with special firmware (test proms). If you want to order 
the test-CP please contact PCS. 

PARAM-LIST 

pass Number of test passes or 0 for infinite test loop. The default value 
is 1 . 

test A list of testnumbers in the range 0 to 2. If no test-list is specified 
all tests are executed by default. During a test pass the tests are 
executed in increasing order. 

0 DMA-read - read blocks of data from memory. 

1 DMA-write - write blocks of data to memory. 

2 DMA-move - read blocks of data from memory and write to 
memory. 

unit Number of the associated DMA - extension register (0 2 31 
Default = 0 (DERO). ' ' ' 

si DMA request time in ms (5..255). Default = 5 ms. 

dialog The test program asks interactively for test commands. 

EXAMPLES 

Test with 100 passes, DMA extension register 2, DMA request time 255 ms. 
tdma pass=0 unit=2 si =255 
Interactive testing 
tdma dialog 

SEE ALSO 

Kurzbeschreibung fur DMA-Testprogramm des QU68030/50 

CADMUS Testmonitor Benutzeranleitung — 

BUGS 

Tdma works fine only with a VTlOO-compatible terminal. 
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Beschreibung 

fur 

Speichertestprogramm MBM Tst 
Martin Ord'ber 

Periphere Computer Systeme 
PfSlzerwald Str. 36 
D-8000 Miinchen 90 








1. Einleitung 

Das Testprogramm "MEMTST" ist ein Speichertestprogramm. das in 68000- 
Assembler-Sprache geschricben ist. MR Hilfe dieses Programmes kann em 
beliebig grosser Q-Bus- und/oder S-Bus-Speicher ausgetestet werden. 
"MEMTST" ist speziell auf den Prozessor QU68000 (QU68030/50) zugeschnit- 
ten. (Das Programm nutzt das lokale RAM des QU68000.) 
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2. Voraussetzung 
2.1. Hardware 


- QU 68000 System 

- QU 68000 Prozessor 

- Serielle Schnittstelle 

■ FLoppyDisk oder anderer Massenspeicher 

- Terminator 

- Option: parallele Drucker-Schnittstelle mit Drucker 


2.2. Software 

• CADMUS Testmonitor 
- Testprogramm MEMTST 

"MEMTST" ist ein Standalone-Testprogramm, das ohne Betriebssystem lauft. 
Gestartet wird ''MEMTST*' rom Testmonitor. Optional kann "MEMTST" auch 
direkt vom Minitor geladen werden. 
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3. Bedienerfuhrung 

3.1. Laden und Starten dea Testprogrammes 
Durch Angabe des Programmnamens 
me mist 

wird "MEMTST" vom Teslmonitor geladen. Ohne Testmonitor kann "MEMTST" 
auch direkt vom "Minitor" mit folgenden Befehlen geladen werden. 

Eingabe: 

rx<cr> Laden von Floppy 

/memtst<cr> 

gO<cr> 

Nach jedem <cr> meldel sich der "Minitor" mit dem Prompt. Durch gO wird 
das Programm gestartet. 

Memtst meldet sich mit folgender Systemausgabe. 

QU68000 - MEMORY TEST Vers, x.x 

Prozessor - Version : MC 680Xx 
____i_ 

***** Lokaler RAM-Bereich O.k. *•••• 

Gesamt-Speicherkapazitaet OOxxxx KByte o.k. (CR/n) ? 

Das Programm stellt selbststaendig die Grosse des Speichers fest. Die Grosse 
wird durch obigen Ausdruck angezeigt und muss durch Eingabe von "j" oder 
<cr> bestatigt werden. 


Testprogramm-Auswahlliste: 


Housenumber 

= 0 

Read/Modify/Write 

= 5 

Random 

= 1 

Write Byte 

= 6 

Bit-Shifting 

= 2 

Write Long Word 

= 7 

Refresh 

= 3 

Parity 

= 8 

Opcode 

= 4 

Force Parity Error 

= 9 


Tests 0....8 

= CR 


Testnummer (getrennt d. V) : 

Das Programm bietet mehrere Testmodule zur Auswahl an. Beschreibung der 
Testmodule siehe Programmbeschreibung. Nach dem Ausdruck der System- 
meldung hat das Programm den lokalen Speicherbereich des QU68000 bereits 
getestet. Tritt bei diesem Test ein Fehler auf, wird dies durch eine 
entsprechende Fehlermeldung angezeigt. Der lokale RAM-Bereich des 
QU68000 wird fur den weiteren Programmablauf benutzt. 

3.2. Programmeingaben 
Testnummer (getrennt d. Y) : 

Hier koennen die verschieden Tests ausgewaehlt werden, die ausgefuehrt wer¬ 
den sollen. Es koennen auch mehrere Tests ausgewaehlt werden. Die einzel- 
nen Tests sind durch zu trennen. Wird nur <CR> eingegeben, werden die 
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Tests 0-8 ausgefuehrt. 

Fuer den Test 8 (Parity) muss der Speicher entsprechend den Standardein- 
«uf Sng BDAU6. 5 “■ ffort ‘ Parit yU«‘>ertr ae u„ 8 

SpeiJher S ^ 

Speicher-Teilbereich testen (j,CR) ? 

Soli nur ein Teilbereich des Speichers getestet werden muss hier "j" einceee- 
ben werden. Mit "n" oder <cr> wird der gesamte erkannte Speicher getestet 
Bei einem Prozessor mit S-Bus-Speicher kann das Speichertestprogramm 
ueber den S-Bus oder ueber den Q-Bus ablaufen. Die Auswahl wird mit der fol- 
genden Abfrage getroffen. 

S-Bus abschalten (j,CR) ? 

Dauertest ? 

Es besteht die Moglichkeit, das Programm im Dauertest zu betreiben. 


3.3. Testprotokoll auf Drucker ? 

Das Testprotokoll kann zusaetzlich zur Terminal-Ausgabe auf einem Drucker 
ausgegeben werden. Bei Dauertest werden nur die Fehlermeldungen ausgege- 
ben. Wird eine Anzahl von 20 Druckseiten ueberschritten, wird die Druck- 
erausgabe automatisch beendet. 

3.4. Programm-Abbruch 

Das Programm kann jederzeit durch die Eingabe von "Contr C" abgebrochen 
werden. 


3.5. Fehler- und Statusreport 

Waehrend des Programmlaufes wird immer angezeigt, welcher Teiltest gerade 
laeuft. Durch Druecken einer beliebigen Taste (ausser Contr C) wird eine Sta- 
tuszeile ausgegeben. Die Ausgabe enthaelt: Test-Nr., Adresse und Testmuster 
der gerade getesteten Speicherzelle. 

Bei Fehlern wird durch das Fehlerprotokoll die Art des Fehlers angezeigt. 

3.6. Testdauer 

Ein Durchlauf der Tests 0-8 dauert fuer 512 kB ca. 6 Minuten. 
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4. Kurzbeschreibung der Testmodule 


4.1. Housenumber-Test 


Der Housenumber-Test wird in mehreren Durchlaeufen ausgefuehrt. Im 
1 Durchlauf - Lower Word Up - werden die Worte im angegebenen Speicher¬ 
bereich mil dem unteren Wort ihrer 22 Bit-Adresse in aufsteigender 
Adressfolee beschrieben. Nach dem Schreiben eines Worts wird es geprueft; 
ist der ganze Speicherbereich beschrieben erfolgt eine zweite Pruefung mit 
der sich eine "Adressverkopplung abwaerts" innerhalb eines 64 KByte- 
Bereichs feststellen laesst. 


Der 2.Durchlauf - Lower Word Down - fuehrt denselben Test mit abfallender 
Adressfolge durch, d.h. er beschreibt den Speicher von "oben" nach ’’unten''. 
Auf diese Weise laesst sich eine "Adressverkopplung aufwaerts" erkennen. 


Im 3 und 4.Durchlauf - Upper Word Up/Down - werden die Tests 1 und 2 mit 
dem oberen Wort der 22 Bit-Adresse durchgefuehrt, urn Adressverkopplungen 
ueber die 64 KByte-Grenzen hinaus feststellen zu koennen. 


Die Durchlaeufe 5-8 - Lower Word Complement Up/Down und Upper Word 
Complement Up/Down - entsprechen den Tests 1-4, nur werden hier die kom- 
plentierten Daten verwendet, um auch Adressverkopplungen mit invertierten 
Bits erkennen. 


4.2. Random-Pattem-Test 


Im Random-Test wird der Speicherbereich mit einem reproduzierbaren 
"Zufalls"-Bitmuster wortweise beschrieben, wobei fuer jedes Wort ein neues 
Bitmuster berechnet wird. Danach erfolgt das wortweise Lesen und Ver- 
gleichen mit den erneut berechneten Bitmustern. 
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4.3. Bit-Shifting-Test 


Der Bit-Shifting-Test besteht aus 34 Durchlaeufen in denen jeweils der ganze 
Speicherbereich mit demselben Bitmuster getestet wird. Der 1 Durchlauf 
verwendet das Bitmuster 111111111111 111 11 ill, der 2.Durchlauf das Bit- 
muster 11111111111111111110. Die Muster der naechsten 15 Durchlaeufe 
werden durch Linksschieben der 0 erzeugt. Anschliessend folgen weitere 17 
Durchlaeufe mit den invertierten Bitmustern. 


4.4. Refresh-Test 


Beim Refresh-Test wird der Speicherbereich mit einem Schachbrett-Muster 
wortweise beschrieben und nach 5 Sekunden Wartezeit geprueft. Danach wird 
der Test mit dem invertierten Bitmuster wiederholt. 


4.5. Opcode-Test 


Beim Opcode-Test wird der Speicherbereich mit dem Opcode des RTS-Befehls 
(Return from Subroutine) beschrieben und anschliessend auf jedes Wort ein 
CALL-Befehl ausgefuehrt. Dann wird der Speicherbereich daraufhin geprueft, 
ob durch die Ausfuehrung der RTS-Befehle der Inhalt von Speicherzellen 
veraendert wurde. 


4.6. Read/Modify/Write-Test 


Der Read/Modify/Write-Test prueft den TAS-Befehl. der als einziger Befehl 
des MC68000 einen unteilbaren Zyklus fuer Lesen/Schreiben benutzt. Dazu 
wird der Speicherbereich byteweise geloescht und mit dem TAS-Befehl das Bit 
7 auf 0 getestet und gesetzt (TAS = Test And Set). Mit einem zweiten TAS- 
Befehl wird geprueft, ob der erste TAS das Bit 7 gesetzt hat. Eine Fehlermel- 
dung kann damit sowohl beim ersten TAS als auch beim Zweiten ausgegeben 
werden. 
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4.7. Write-Byte-Test 


Der Write-Byte-Test beschreibt den Speicherbereich byteweise mit einem 
Schachbrettmuster und prueft jedes Byte sofort nach dem Schreiben. 


4.8. Write-Long-Word 


Der Write-Long-Word-Test beschreibt den Speicherbereich doppelwortweise 
mit einem Schachbrettmuster und prueft jedes Doppelwort sofort nach dem 
Schreiben. 


4.9. Parity-Test 


Der Parity-Test beschreibt im l.Durchlauf den Speicherbereich wortweise mit 
einem Bitmuster mit gerader Bit-Anzahl. Danach wird jedes Wort gelesen und 
gleich wieder zurueckgeschrieben (Move memory to memory - Befehl). Das ist 
notwendig, da das Testprogramm im lokalen RAM ablaeuft und zur Erkennung 
eines Parity-Fehlers (Bus Error) zwei aufeinanderfolgende Q-Bus-Zyklen 
erforderlich sind. was bei dem verwendeten Befehl der Fall ist. Der 2.Dur- 
chlauf verwendet ein Bitmuster mit ungerader Bit-Anzahl. 


4.10. Force-Parity-Test 


Der Force-Parity-Error-Test setzt im Prozessor-Control-Register das FPE-Bit 
und beschreibt den Speicherbereich wortweise mit einem Bitmuster mit 
gerader Bit-Anzahl. Danach wird jedes Wort gelesen. wobei jeweils ein Parity- 
Fehler (Bus Error) auftreten muss, der vom Testprogramm abgefangen wird. 
sonst erfolgt eine Fehlermeldung. Dasselbe wird mit einem Bitmuster mit 
ungerader Bit-Anzahl wiederholt. 
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1. Einleitung 

Das Programm t68030 Version 3.1 ist aus dem Programm t68030 Version 1.1 
entstanden. In der Version 3.1 wurden auch die Eigenschaften des Prozessors 
MC 68010 (Motorola) beriicksichtigt. Der MC 68010 besitzt ein anderes 
Error-Handling als der MC 68000. Ausserdem wird beim Prozessor MC 68010 
mit einer zusatzlichen Testroutine *pf' die Page-Fault-Option Oberprvift. FQr 
diesen Test ist der Prozessor QU68050 notwendig. Die zweite MMU-Stufe dieses 
Prozessors wird aber nicht ausgetestet. 

Die Version 3.1 wird unter dem CADMUS Testmonitor aufgerufen und mit 
Parameter versorgt (siehe t68030(TM)). 
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2. Struktur des Programing 

Das gesamte Programm besteht aus folgenden Moduln: 
Hauptprogramm 
10 Testroutinen 
1/0-Routinen 


3. Laden und Starten des Programms vom Testmonitor 
@t68030 [param-list] 

Filr eine detailierte Beschreibung siehe t68030(TM). 

4. Bedienung des Programing bei Aufruf mit dialog 
Zunachst werden 2 Fragen an den Bediener gestellt: 

- Ob der Prozessor-Typ QU 68050 (mit MMU-Stufe 2) getestet werden soil. 

In diesem Fall wird der MMU-Test (siehe Abschnitt 5) nicht durchlaufen. 

- Ob der verwendete Speicher die Erzwingung eines Parity-Fehlers (force 
parity error) erm&glicht. 

1st dies nicht der Fall, dann wird der Force-Parity-Error-Test (fp) aus- 
gelassen. 

Nun kann der Testlauf gestartet werden. Dabei gibt es im wesentlichen 2 
unterschiedliche Betriebsarten: 

single 1 Testdurchlauf 

Die Testroutinen werden nur je lx durchlaufen. Am Beginn und 
Ende einer jeden Routine und im Fehlerfall erscheint eine Meldung 
auf dem Bildschirm. Wahlweise ist hier auch eine Ausgabe auf 
Drucker moglich. 

dauer Dauertest 

Die Testroutinen werden fortlaufend nacheinander betrieben. Der 
Abbruch erfolgt durch Tastatureingabe oder wahlweise auch im 
Fehlerfall. Es wird im Normalfall nur die Anzahl der Testdurchlfiufe 
und die Anzahl der Fehler je Testroutine (wenn ungleich Null) 
angezeigt. Die Fehlerz&hler werden pro Durchlauf um max. 1 erhoht 
(im Gegensatz zum Einzeltestdurchlauf, bei dem die genaue Anzahl 
der Fehler der jeweiligen Routine ausgegeben wird). 

In beiden Betriebsarten kann im Fehlerfall der Test abgebrochen werden 
(Stop bei Fehler); es wird dann keine weitere Testroutine aufgerufen. Beim 
Dauertest kann dabei wahlweise die ausfvihrliche Fehlerinformation angezeigt 
werden (wie beim Einzeltest). 

Einige Testfunktionen konnen im Dauertest nicht durchgefiihrt werden 
(ROM-Test, BUS-INIT-Test). Deshalb sollten immer beide Betriebsarten benvitzt 
werden. 

Alle Bediener-Eingaben konnen bis auf den l.Buchstaben abgekurzt werden. 

Durch Betatigen der Taste ’NO SCROLL’ kann die Ausgabe auf das Terminal 
jederzeit unterbrochen werden (es wird auch die Ausfuhrung des Programms 
angehalten). Der Smooth-Scroll-Mode des VT100 und DSG101 wird ebenfalls 
unterstutzt. 
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5. Beenden des Programms 
Funktion: ’ende’ eingeben. 

Die Kontrolle wird an den Testmonitor zuriickgegeben. 

6. Vorhandene Testroutinen 

et Test der elementaren Prozessorfunktionen 

Bedingte Verzweigungen, Compare-Befehle, Register-Test, byte-weise 
schreiben und lesen vom Speicher, TAS-Befehl mit dem Speicher (Read- 
Modify-Write-Zyklus) 

ad Test der Adressierungsarten 

Alle auf den Speicher wirkenden Adressierungsarten werden durch 
Schreib- und Lese-Zugriffe mit den Operandengrdssen Byte, Wort und 
Doppelwort getestet. 

bel Test der 1-Operanden-Befehle 

Alle 1-Operanden-Befehle (ausgenommen Sprung-, Verzweigungs-Befehle 
und Befehle mit Sonderfunktionen) werden mit verschiedenen Datenwer- 
ten und mit den Operandengrossen Byte, Wort und Doppelwort getestet. 
Die Operanden befinden sich im Datenregister 4 (ausser bei Shift- 
Befehlen). Nach der ausgefuhrten Operation wird auch der Inhalt des 
Condition-Code-Registers auf Richtigkeit ttberpriift. Im Fehlerfall werden 
der Befehl, der Operand, Soli- und Ist-Wert des Ergebnisses und des 
Condition-Code-Registers angezeigt. 

be2 Test der 2-0peranden-Befehle 

Alle 2-0peranden-Befehle (ausgenommen Immediate-Befehle, Befehle mit 
Sonderfunktionen und Befehle, die nur auf Adressregister wirken) wer¬ 
den mit verschiedenen Datenwerten und mit den Operandengrdssen Byte, 
Wort und Doppelwort getestet. Die Operanden befinden sich in den 
Datenregistem 2 und 4. Nach der ausgefuhrten Operation wird auch der 
Inhalt des Condition-Code-Registers auf Richtigkeit uberpriift. Im Fehler¬ 
fall werden der Befehl, die Operanden. Soil- und Ist-Wert des Ergebnisses 
und des Condition-Code-Registers angezeigt. 

rr RAM/ROM-Test 

Bei Einzeltestdurchlauf (single) wird uber den ROM-lnhalt (alle 3 Teil- 
bereiche) eine Prufsumme erzeugt und ausgedruckt. Diese Priifsumme 
darf sich nicht andern, solange dieselbe Minitor-Version verwendet wird. 
Die Kontrolle muss manuell erfolgen. 

Das interne RAM wird durch Einschreiben eines Testmusters (im 1. und 2. 
Testteil) bzw. durch Einschreiben der Adresse (im 3. Testteil) und 
auslesen des Inhalts uberpriift. 

Achtung, durch diese VerSnderung des RAM-Inhalts wird die Information 
iiber evtl. gesetzte Breakpoints iiberschrieben. 

mt MMU-Test 

Beschreiben der Basisadressregister und lesen der erzeugten phys. 
Adresse uber den Page-Deskriptor. 
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Es wird nur die MMU-Stufe 1 getestet. Beim Test des QU 68050 wird diese 
Routine nicht durchlaufen. 

Beim QU 68030 kann das Page-Deskriptor-Register (PD) verwendet wer- 
den, um die durch die MMU erzeugte physikalische Adresse zu lesen. 

Im Anlaufzustand, der hier beim Ansprechen des PD-Registers gewahlt 
wird. sind fur die Adressierung des PD-Registers die Bits 0...14 
ausreichend. Die Bits 15... 19 werden nur zur Bildung der phys. Adresse in 
der MMU herangezogen. Die Bits 20...23 wahlen eines von 15 MMU- 
Segmenten aus (das Segment 0 wird hier nicht verwendet). Die Bits 9...21 
der durch die MMU erzeugten phys. Adresse konnen aus dem PD-Register 
gelesen werden. 

In diesem Programm werden die Basis-Adress-Register (BAR) und 
Addierer der MMU getestet durch Verwendung von 15 Segmenten, ver- 
schiedener BAR BAR-Inhalte und verschiedener Adressbit 15... 19 des auf 
das PD-Register zugreifenden Befehls. 

Segment 0 wird nicht getestet. 

Beim Test des Segment 15 gelten folgende Einschrankungen: 

- Beim Segment 15 aufgetretene Fehler werden zwar registriert (der 
Fehlerzahler wird erhoht), beim Einzeldurchlauf erfolgt aber kein 
genauer Fehlerausdruck, da der ZugrifT auf die DLV-11 tiber den Q- 
BUS nur mit ganz bestimmten BAR-Inhalten moglich ist. 

- Es konnen keine Breakpoints verwendet werden. Dies kann vermieden 
werden, indem der Test mit Segment 14 (statt 15) begonnen wird: 
Equate ’maxseg* entsprechend andem. 

sd Test der Segmentdeskriptoren der MMU 

Die Segmentdeskriptoren werden beschrieben, Testzugriffe (Daten 
schreiben, Daten lesen, Code Fetch) auf das jeweilige Segment ~ 
ausgefiihrt, die zum Teil gegen den gewahlten Segment-Schutz verstos- 
sen (Trap!) und in diesen Fallen die Fehler-Anzeige im ESR kontrolliert. 
Segment 0 wird nicht getestet. 

Beim Test des Segment 15 gelten die gleichen Einschrankungen wie beim 
MMU-Test. 


ir Interrupt-Test 

Testet das Bus-Event-Signal (Linetime-Clock) und den Ausgabe-Interrupt 
vom Interface der Console. 

In beiden Fallen wird der Interrupt zunSchst durch eine hohere Prioritat 
im Status-Register gesperrt, nach einiger Zeit die Prioritat emiedrigt 
und die Zeit zwischen 2 Interrupts grob kontrolliert. (Die Baudrate des 
Terminals sollte deshalb zwischen 4800 und 19200 Bd liegen.) 

Bei Einzeltestdurchlauf (single) wird zusatzlich das Bus-Init-Signal am 
Q-Bus getestet. Dies geschieht Ober das Interrupt-Enable-Bit des 
Consolen-Interface: Nach dem Bus-Init-Signal darf kein Interrupt mehr 
auftreten. 

Im Fehlerfall wird eine Fehlertyp-Nummer angezeigt, sie hat folgende 
Bedeutung: 

Fehlertyp 
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I Interrupt von der Linetime-Clock ist aufgetreten, obwohl die 
Prioritat im Statusregister hoher sein sollte. 

2...4 Der erwartete Interrupt von der Linetime-Clock ist ausgeblieben 
bzw. nicht innerhalb einer bestimmten Zeit gekommen. 

5 Der Abstand zwischen 2 Interrupts von der Linetime-Clock war 
zu kurz. 

6 Interrupt vom Consol-Interface ist aufgetreten, obwohl die 
Prioritat im Statusregister hoher sein sollte. 

*7...9 Der erwartete Interrupt vom Consol-Interface ist ausgeblieben 
bzw. nicht innerhalb einer bestimmten Zeit gekommen. 

10 Der Abstand zwischen 2 Interrupts vom Consol-Interface war zu 

kurz. 

II Interrupt vom Consol-Interface kam, obwohl uber den RESET- 
Befehl des 68000 ein Bus-Init ausgelost wurde. 

12 Interrupt vom Consol-Interface kam, obwohl uber das 

Processor-Control-Register (PCR) ein Bus-Init ausgelost wurde. 

fp Force-Parity-Error-Test 

Erzwingt durch 'force parity error' ein fehlerhaftes Parity-Bit im 
Speicher und kontrolliert, ob beim Auslesen dieser Zelle die richtige 
Fehlerreaktion erfolgt (Bus-Error, Inhalt des ESR). 

Einige Speicher fur den Q-Bus unterstutzen diese Moglichkeit nicht; dies 
fiihrt dann zu einer Fehleranzeige. 

bt BUS-Timeout-Test 

Erzwingt einen BUS-Timeout durch Beschreiben einer nicht vorhandenen 
Speicherzelle (Adresse E00000 hex) und kontrolliert die Fehlerreaktion. 
(Bus-Error, im ESR muss das Timeout-Bit oder das Page-Fault-Bit gesetzt 
sein.) 
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1. Voraussetzung 

1.1. Hardware 


- CADMUS System 

- QU 68050 Prozessor 

- mindestens 512 kByte Speicher 

- Serielle Schnittstelle 

- FLoppyDisk oder anderer Massenspeicher 

- Terminator 


1.2. Software 

- CADMUS Testmonitor 

- Testprogramm t68050 

2. MMU2-Test: t68050 

2.1. Laden und Starten des Programms vom Testmonitor 
@t68050 [param-list] 

Fur eine detailierte Beschreibung siehe t68050(TM). 

2.2. Laden und Starten des Programms durch den Mini tor 

,rx (laden von der Floppy) 

,/t68050 
.g (Start) 

(Der Punkt ist das Minitor-Prompt-Symbol.) 


2.3. Programmausgabe: 

Memory von xxx bis xxx (hex) 
loop xxx error xxx 

Erklarung zum Ausdruck: 

Loop gibt die Anzahl der Durchlaufe an. 
error gibt die Summe der Fehler an. 

Memory von x bis x verfligbarer Testspeicher 


3. Kurzbeschreibung des Programms 

Die Grosse des Testspeichers wird angezeigt. Innerhalb des Testspeichers wer- 
den virtuell 16Mbyte dargestellt. 

Das Programm testet ob beim Beschreiben des Seitendiskriptors die beiden 
Statusbits gleich 0 und bei einem entsprechenden Bus-Zyklus (Lese-, 
Schreibzugriff) auf 1 gesetzt wurden. Wird auf eine gerade nicht im Speicher 
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befindliche Seite oder auf eine nicht definierte Seite zugegriffen wird ein 
Page-fault ausgeloest. 

Kachel 0-12 und 1023 werden nicht getestet. 

Bei loop 0,1.2 ...,usw wird die Adresse (loop • 4) innerhalb jeder Kachel 
getestet. 

4. Fehlermeldung 
z.B. 

bus error nicht eingetroffen 
kachel = xxx viradr = xxx pd = xx -> aaa -> bbb 
loop xxx error xx 

kachel Kachelnummer 
viradr virtuelle Adresse 
pd Inhalt des Page-diskriptors 

-> aaa Zugriff (Test, Lese-, Schreibzugriff) 

-> bbb Testsollstatus der Kachel 
loop Anzahl der Durchlaufe 
error Summe der Fehler 

kaadr Kacheladresse 
mmu3 Inhalt der mmu3 (offset) 


5. Programmabbruch 

Das Programm kann durch CTRL-C abgebrochen werden. 
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1. DMA-Test: DMATST 

1.1. Laden und Starten des Programms vom Testmonitor 
@tdma [param-list] 

Fur eine detailierte Beschreibung siehe tdma(TM). 

1.2. Laden und Starten des Programms durch den Mini tor 

.rx (laden von der Floppy) 

./tdma 

.g (Start) 

(Der Punkt ist das Minitor-Prompt-Symbol.) 


1.3. Bedienung des Programms bei Aufruf mit dialog 

Es gibt 3 unterschiedliche Betriebsarten. Diese sind: Read, Write und Move. 
Moglich sind auch Kombinationen der drei verscheidenen Betriebsarten. 

Testmemory von XXX bis YYY (hex) (j/n) 

Die Grosse des Speichers wird uberpruft. Bei Eingabe von <n> kann ein 
anderer zu testender Speicherbereich ausgewahlt werden. Ein'gaben sind 
dann: Startadresse und Endadresse des zu testenden Speichers. Die 
Grosse des zu testenden Speichers muss mindestens 2000 (hex) Byte 
sein. Nach der Eingabe wird OberprOft, ob der Speicher wirklich im Sys¬ 
tem ist und zur Best&tigung nochmals abgefragt. Bei Fehlem in der 
Eingabe wird eine neue Eingabe erwartet. 

1m DMA-Betrieb wird blockweise vom Speicher gelesen. 

Im DMA-Betrieb wird blockweise in den Speicher geschrieben. 

Im DMA-Betrieb wird vom Speicher gelesen und auf den 
Speicher geschrieben. 

Bei ja befindet sich das Programm in einer Endlosschleife die 
nur durch CTRL C unterbrochen werden kann. Bei nein wird 
nur ein Durchlauf gemacht. 

Eingabe des zu verwendenden DMA-Extensionregisters. 
Befindet sich am Backplane keine Zusatzverdrahtung muss 
das DER 0 verwendet werden. 

Hier kann die Anzahl der DMA-Requests pro Sec. eingegeben 
werden. Mogliche Eingaben sind 5 - 255 ms. 

Programmausgabe: 

Loop xx Ges.Error xx DMA-Time xxx 


DMA-Read (j/n) 
DMA-Write (j/n) 
DMA-Move (j/n) 

Dauertest (j/n) 

DER 

DMA-Req.Time 
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akt 

buserr 

checks 

read 

• * 

XX 

XX 

writ 

* * 

XX 

XX 

move 

• » 

XX 

XX 


Erklaerung zum Ausdruck: 


intimo 

daterr 

adress 

went 

XX 

XX 

XX 

XX 

XX 

XX 

XX 

XX 

XX 

XX 

XX 

XX 


Loop 

akt 

buserr 

checks 

intimo 

daterr 

adress 

went 


Anzahl der Durchlaufe 

gerade aktive Funktion 

Anzahl der aufgetretenen Busfehler 

Anzahl der aufgetretenen Checksummen-Fehler 

Anzahl der Timeout-Fehler 

Anzahl der Datenfehler 

Adresse bei der ein Datenfehler aufgetreten ist 
Wordcount bei aufgetretenem Datenfehler 


1.4. 

Das Programm kann durch CTRL C abgebrochen werden. 
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1. Einleitung 

Das Programm testet die Schreib-, und Lesefunktion des Omti 20d bzw. DTC 
520A Controllers in Verbindung mit 5 1/4" Winchester-, oder Floppy- 
laufwerken. Ein Controller kann max. zwei Winchester und zwei Floppys 
bedienen. Es werden sektorweise Daten auf die Floppy bzw. Winchester 
geschrieben und wieder gelesen. Hierzu wird nicht der UNIX-Treiber, sondem 
eigene Subroutines benutzt. Durch Datenvergleich und durch Abfrage der 
Controller Fehleranzeigen oder durch Timeout werden Schreib-, Lese-, und 
Datenfehler erkannt. 


2. Voraussetzung 

2.1. Hardware 

- CADMUS System 

- Serielle Schnittstelle 

- FLoppy Disk oder anderer Massenspeicher 

- OMTI 20D oder DTC 520 Controller und 5 1 /4 " Winchester 

- SCSI - Adapter 

Adresse: FFFB80(16) Vektor: 230(8) 

- Terminator 

2.2. Software 

- CADMUS Testmonitor 

- Testprogramm SCSITST 

''SCSITST” ist ein in C geschriebens Testprogramm. das mit dem Testmonitor 
gestartet wird. 


3. Bedienerfuhrung 

3.1. Laden und Starten des Testprogrammes 
@scsitst [param-list] 

Fiir eine detailierte Beschreibung siehe SCSITST(TM). 

Bei Start mit dialog meldet sich das Programm mit folgender Systemausgabe. 
•• OMTI 20D DTC-520A Test-Programm ** 

0= OMTI 20D 
1 = DTC-520A 
enter controller type : 

Abfrage nach welchem SCSI-Controller 
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0= TM 503 
1= TM 603 
2- TM 703 

3 - floppy 

4 = RO 208 
5= MAX 1065 
6= BASF 6185 
enter drive type : 

Abfrage nach welchem Massenspeicher 
unit 

0..1= Yfinchester 
2..3 = Floppy 
enter unit [0..3] : 

Abfrage nach welchem Winchester-, bzw. Floppy-Laufwerk. 0=1., 1=2. 

Winchester-Laufwerk, 2=1., 3=2. Floppy-Laufwerk. 


Das Programm bietet mehrere Testmodule zur Auswahl an. 

Testprogramm-Auswahlliste: 

0 = read block 

1 = urrite block 

2 = read sequent 

3 = unrite sequent 

4 = unrite + read + compare sequent 

5 = unite + read + compare zigzag 

6 = unrite sequent read + unrite random 
enter test number : 

Hier konnen die verschieden Tests ausgew&hlt werden. 

test with move multiple [y/n] : 

Uebertragungsmodus wort-, bzw. blockweise. 
continous test [y/n] : 

Es besteht die Moglichkeit, das Programm im Dauertest zu betreiben. 


3.2. Programm-Abbruch 

Das Programm kann jederzeit mit "CTRL C" abgebrochen werden. 


3.3. Fehler- und Statusreport (S) 

Wahrend des Programmlaufes wird immer angezeigt, welcher Teiltest gerade 
lauft. Durch Driicken der S-Taste wird eine Statuszeile ausgegeben. Die Aus- 
gabe enthalt: Test-Nr., Anzahl der Durchlaufe und Summe aller Fehler. 
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3.4. Anhalien der Bildschirmausgabe (W) 

Um ein Weglaufen des Bildschirminhaltes zu verhindern wird mit der W-Taste 
die Ausgabe angehalten. Nach Erkennen der Wait-Funktion wird dies mil "con¬ 
tinue <cr>" am Bildschirm angezeigt. Mit der Return-Taste wird die Ausgabe 
wieder fortgesetzt. 


4. Kurzbeschreibung der Testmodule 

4.1. Read Block - Write Block 

Bei Read Block bzw. Write Block kann ein beliebiger Sektor innerhalb der 
angegebenen Grenzen ausgewahlt werden. Bei ungultiger Sektorgrosse wird 
die Abfrage wiederholt. Nach dem Lesen bzw. Schreiben wird getestet ob ein 
Fehler aufgetreten ist. 


4.2. Read sequent Write sequent 

Auf der Winchester bzw. Floppy werden fortlaufend alle Sektoren mit einem 
festen Datenmuster beschrieben bzw. gelesen. 


4.3. Write Read Compare sequent 

Auf der Winchester bzw. Floppy wird fortlaufend ein Zylinder beschrieben, 
gelesen und die gelesenen Daten mit der Sollinformation verglichen. 
Zwischen Schreiben und Lesen findet keine Kopfbewegung statt. 


4.4. Write Read Compare zigzag 

Vom diesem Test werden die Sektoren alternierend (1. Sektor, letzter Sektor, 
2. Sektor, usw) ausgewahlt, beschrieben, gelesen und mit der Sollinformation 
verglichen. 


4.5. Write sequent Read Write random 

Das zu testente Medium wird sequentiell beschreiben. Danach wird nach 
Zufall ein beliebiger Sektor ausgewahlt, gelesen und mit der Sollinformation 
verglichen. Nun wird der Sektor mit eimem anderen Muster beschrieben. 
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1. Einleitung 

Das Programm "SLUTST" testet das SLS-48 bzw. SLS-88 Interface im 
Kurzschluss. Der Test arbeitet mit Interrupts. Es wird mit Baud-Raten 
zwischen 110 Baud und 9600 Baud getestet. 


2. Voraussetzung 
2.1. Hardware 

- CADMUS System (CPU + Speicher) 

- Serielle Schnittstelle DLVll 

- FLoppy Disk oder anderer Massenspeicher 

- SLS 48 Oder SLS 88 

Adresse: FFFC00(16) Vektor: 300(8) 

- Terminator 


2.2. Software 

- CADMUS Testmonitor 

- Testprogramm SLUTST 

"SLUTST" ist ein in C geschriebenes Testprogramm, das mit dem Testmonitor 
gestartet wird. 


3. Bedienerfuhrung 

3.1. Laden und Starten des Testprogrammes 
©slutst [param-list] 

Fur eine detailierte Beschreibung siehe SLUTST(TM). 

Bei Start mit dialog meldet sich das Programm mit folgender Systemausgabe. 

SLU - TESTPROGRAMM 
Keyboard Commands: 

''C: Abbruch S: Show W: Wait <Ret> : Continue 


Schaltereinstellung: Si ... S8 — off 

S9 ... SO = on 

Schaltereinstellung ok ? 

Nach Ueberpriifung des 10 pol. Miniaturschalters auf korrekte Einstellung ist 
diese Abfrage mit Return zu beantworten. 

Konfigurationsregister: 9600 Baud, Gbit, IStop bit sis 68 

Hier wird der Inhalt des Konfigurationsregisters angezeigt und getestet ob es 
sich um ein sls-48 oder sls-88 Interface handelt. 
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Dauertest [J/N] : 

Bei Dauertest gleich 'J' fQr ja werden alle Tests im Endlos-loop durchgefuhrt. 
Auto-Kurzschlusstest [J/N\ : 

Bei Auto-Kurzschlusstest rrv&ssen folgende Verbindungen hergestellt werden. 

Transmitter: tty40 - Receiver: tty42 
Transmitter: tty42 - Receiver: tty40 
Transmitter: tty41 - Receiver: tty43 
Transmitter: tty43 - Receiver: tty41 
Transmitter: tty44 - Receiver: tty46 
Transmitter: tty46 - Receiver: tty44 
Transmitter: tty45 - Receiver: tty47 
Transmitter: tty47 - Receiver: tty45 

Verbindungen ok ? 


Nach Ueberprufung der vorgeschriebenen Verbindungen ist dies mit Return 
zu quittieren. 

Bei Nicht-Auto-Kurzschlusstest konnen beliebige Verbindungen hergestellt 
werden. 

Sendekanal \tty4x] : 

Empfangskanal \tty4x] : 

X gibt den Kanal (0 .. 7) an. Bei Eingabe von Ctrl C Return wird zur Sen- 
dekanalabfrage verzeigt. 

3.2. Programm-Abbruch (rC) 

Das Programm kann jederzeit mit "Contr C" abgebrochen werden. 


3.3. Fehler- und Statusreport (S) 

Wahrend des Programmlaufes wird immer angezeigt, welcher Teiltest gerade 
lauft. Durch Driicken der S Taste wird eine Statuszeile ausgegeben. Die Aus- 
gabe enthalt: Anzahl der Testdurchlaufe, Summe aller Fehler, Interruptfehler, 
Vectorfehler und Datenvergleichsfehler. 


3.4. Anhalten der Bildschirmausgabe (W) 

Um ein Weglaufen der Terminalinformation zu verhindern wird mit der W- 
Taste die Ausgabe angehalten. Nach erkennen der Wait-Funktion wird dies mit 
"continue <Ret>” am Bildschirm angezeigt. Mit der Return-Taste wird die 
Ausgabe wieder fortgesetzt. 








- 4- 


4. Kurzbeschreibung der Testmodule 

4.1. Auto-Kurzschlusstest 

Bei Auto-Kurzschlusstest werden die oben angegebenen Kanale der Reihe 
nach mit den Baud-Raten 9600 Baud, 4800 Baud, 2400 Baud, 1200 Baud, 600 
Baud, 300 Baud und 110 Baud getestet. Als Datenmuster werden alle 
moglichen Zeichen von 00(hex) bis FF(hex) ubertragen. Am Terminal wird die 
zu testende Verbindung und die augenblickliche Geschwindigkeit angezeigt. 


4.2. Nicht-Auto-Kurzschlusstest 

Bei Nicht-Auto-Kurzschlusstest kann eine beliebige Verbindung zwischen 
einem Transmitter und einem Receiver hergestellt werden. 


5. Systemmeldungen 


5.1. loop error cmperr vecerr interr 


loop 

error 

cmperr 

vecerr 

interr 


Anzahl der Durchlaufe 
Summe aller Fehler 
Anzahl der Datenvergleichsfehler 
Anzahl der Vectorfehler 
Anzahl der Interruptfehler 


5.2. Data Error soil = aa ist = ba cmperr = x 

Datenvergleichsfehler mit Sollmuster gleich aa und Empfangmuster gldich 6a. 
cmperr = x ist der x. Vergleichsfehler in diesem Block. 


5.3. Receiver Interrupt Timeout /dev/tty4z xxxx Baud 
Bei Kanal z(0..7) ist kein Zeichen empfangen worden. 


5.4. Transmitter Interrupt Timeout /dev/tty4z xxxx Baud 

Nach Starten des Kanals z(0..7) ist kein Sendeinterrupt eingetroffen. 


5.5. Interrupts: Transmit = x Receive = y Ext/Status = z Special = w 

x Anzahl der Transmitter Interrupts 

y Anzahl der Receiver Interrupts 

w Anzahl der Ext/Status Interrupts 

w Anzahl der Special Interrupts 
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5.6. Special Receive Condition status bits: 

10(hex) Parity Error 

20(hex) Rx Overrun Error 

40(hex) Framming Error 


5.7. External status bits: 

40(hex) Tx Underrun 

80(hex) Break/Abort 
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1. 

Einleitung 

Diese Testanweisung setzt die Kenntnis folgender Beschreibungen 
voraus: 

- Spezifikation FPP 81 Floating Point Prozessor 

- Hardware-Beschreibung FPP 01 

- Datenblatt NS16081-6 (-10) Floating Point Unit 

- CADMUS Testmonitor Benutzeranleitung 

* 3 

Voraussetzungen 

2.1 

Testhilfsmittel 

- CADMUS-System mit Q22-Bus 

- Minitor Version 2.2 (R900.123) 

- FPP 81 + S-Bus-Kabel 

- DLV 11 oder Multi-Function-Board 

- Platten-, Band- oder Streamer-Laufwerk 

- Platten-, Band- oder Streamer-Controller 

- Terminal 

m 22 

Testprogramm 

fpptst 
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3. Testablauf 

3.1 Sichtkontrolle 

- 1st das Board vollstSndig bestiickt? 

- Befinden sich alle IC’s am richtigen Steckplatz? 

- Stimmt die IC-Richtung? 

- Sind alle Elkos richtig gepolt ? 

- Sind alle Brucken richtig konfiguriert? 


3.2 Kurzschlussprufung 

Messen der 5 Volt Versorgungsspannung auf Kurzschluss 








- 3 - 


3.3 Basistests mit Minitor 

Um die DurchfGhrung einfacher Tests ohne Logic-Analyser zu 
ermoglichen, wurden auf dem FPP 81 ein Test-Register, sowie ver- 
schiedene Test-Sequenzen in den Sequenzer-PROM’s vorgesehen. 


3.3.1 Test-Register 

Das 16 Bit breite Testregister speichert jedes Kommandowort, das an 
die FPU ubergeben wird, bis zum nachsten Befehl. Damit kann durch 
Auslesen des Testregisters gepruft werden, ob das FPU-Kommandowort 
aus der FPP-Adresse richtig umcodiert wurde. Der Zusammenhang 
zwischen FPP-Adresse und Kommandowort ist der Spezifikation (Bild 
3.3 ff.) zu entnehmen. 

Das Testregister kann per Minitor unter der Adresse XXFFF8 (hex) aus- 
gelesen werden. XX ist die Basisadresse des FPP, die Standardeinstel- 
lung ist 3E (hex). 


Beispiel: 


FPP-Befehl ROUNDFB 
Testregister lesen 
Ausgabe 


3E0020.2 <CR> 
3EFFF8.2 <CR> 
2402 


3.3.2 Test-Sequenzen 

Die Testsequenzen im Sequenzer erm8glichen einen Datentransfer vom 
Operanden-Buffer in den Result-Buffer, ohne Beteiligung der FPU. Die 
Umschaltung in den Testbetrieb des Sequenzers erfolgt uber das TST- 
Bit im Command/Status-Register, das mit folgender Minitor-Eingabe zu 
setzen ist: 


3EFFF0-20 


Fuhrt man jetzt per Minitor einen FPP-Schreibzugrifl durch, so erfolgt 
der Transfer von 1,2 Oder 4 Worten vom Operanden- in den Result- 
Buffer. Die Anzahl der Worte hangt vom jeweiligen Befehl ab. Wahlt man 
z.b. einen MOVFF-Befehl (mit ext. Source ), so erfolgt ein 2-Wort- 
Transfer, bei einem MOVLL-Befehl erfolgt ein 4-Wort-Transfer. 
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Beispiele: 

Schreibzugriff mit 1-Wort-Transfer 

3E2800-1234 <CR> 
3EFFE0.2 <CR> 

1234 

Schreibzugriff mit 2-Wort-Transfer 

3E9000-1111 2222 <CR> 
3EFFE0.4 <CR> 

1111 2222 

Schreibzu griff mit 4-Wort-Transfer 


FPP-Befehl MOVWF 
Result-Buffer lesen 
Ausgabe 


FPP-Befehl MOVFF 
Result-Buffer lesen 
Ausgabe 


3ED000-1111 2222 3333 4444 <CR> FPP-Befehl MOVLL 
3EFFE0.8 <CR> Result-Buffer lesen 

1111 2222 3333 4444 Ausgabe 
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3.4 Testprogramm ’fpptst’ 


3.4.1 Uebersicht 

Der Floating Point Prozessor FPP 81 ist als peripherer Prozessor am 
QU68000 angeschlossen und wird mit MOVE-Befehlen entweder fiber 
den Q-Bus oder Uber den S-Bus angesprochen. 

Das Testprogramm 'fpptst* dient als GO/NOGO Test und lauft im 
Standalone-Betrieb oder unter dem CADMUS Testmonitor. Es konnen 
damit Einzel- und Dauertests durchgefiihrt werden. Der FPP sollte 
zuerst ohne S-Bus-Anschluss getestet werden. Erst wenn damit alle 
Testdurchlaufe fehlerfrei sind, ist der S-Bus anzuschliessen. 

Interrupt-Vektor: 231 (oktal) FPP-Basisadresse: 3E0000 


3.4.2 Beschreibung 

Folgende Tests werden bei einem Testdurchlauf ausgefiihrt : 

1 . Befehls-Tests ( Tests 1 .. 19,21,22 ) 

Alle Floating-Point-Befehle (ausser Double-Precision) werden 
mit verschiedenen Adress-Modes fiberpruft. 

2. Compare(CMP)/CSR-Test ( Test 20) 

In diesem Test werden der COMPARE-Befehl und die Statusbits 
der FPU (Negative und Zero), die bei diesem Befehl ins CSR 
iibertragen werden, geprfift. 

3. Adress-Mode-Tests 

- Schreibzugriff: 

Source extern. Destination intern ( Test 23 ) 

Source intern. Destination extern ( Test 24 ) 

- Lesezugriff: 

Source intern. Destination extern ( Test 25 ) 

Source intern. Destination intern ( Test 26 ) 

Source intern. Destination intern ( Test 27 ) 

- Registerpointertests: ( Tests 23..27 ) 

Die Schreib/Lese-Zugriffe (auf Reg. FO) werden wiederholt, 
wobei der interne Operand jeweils durch den Registerpointer 
adressiert wird. FQr den Registerpointer werden die Modes 
(RP), -(RP), —(RP), (RP)+ und (RP)++ verwendet. Beim Test 27 
erfolgt eine Kombination aller Register-Pointer-Modes 
untereinander (z.b. -(RP),(RP)++). 
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4. TRAP-Test ( Test 28) 

In diesem Test wird die Trap-Condition der FPU Qberpnift. Der 
Trap wird durch einen ZERO DIVIDE ausgelost, wobei ein Inter¬ 
rupt erzeugt werden muss. 

5. DOUBLE-PRECISION-Test ( Test 29) 

In diesem Test wird der Befehl MOVLL (mit Double-Precision- 
Zahl) gepriift. 

6. OP.BUFFER-RES.BUFFER-TRANSFER-Test (Test 30) 

In diesem Test wird mit Hilfe einer Testsequenz im Sequenzer 
die Datenubertragung vom Op-BufTer in den Res-BufTer (ohne 
Beteiligung der FPU) gepriift. 

Die vorhandenen Tests kann man entweder im Single- oder im Loop- 
Betrieb starten. Im Loop-Betrieb kann der Test durch Eingabe von Ctrl Z 
gestoppt werden, durch Eingabe des Kommandos ’e’ wird das Testpro- 
gramm abgebrochen. 

Die Fehler, die wahrend der Tests auftreten, werden durch Fehlerzahler 
und Fehlermeldungen auf dem Bildschirm oder Drucker protokolliert. 
Der Abbruch des Testprogramms im Fehlerfall kann wahlweise angege- 
ben werden. 


3.4.3 Bedienung 

Mogliche Kommandos: 


Sxy 

Szz 

Lxy 

Lzz 

Cxy 

G 


Einmalige Durchfiihrung 

Einmalige Durchfiihrung 

Dauertest 

Dauertest 

Losche Test Nr. xy 

Start 

Exit 


des Test Nr. xy 
aller Tests 
des Test Nr. xy 
aller Tests 


E 


zz = (maximale Anzahl der Tests) + 1 

xy = maximal zweistellige Zahl zwischen 0 und (zz-1), 
z.B <01>,< 2>,<3> 
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3.4.4 Fehlermeldungen 

Tests 10.11.14.15.16.17: 

Zusatzlich zum Fehlerzahler wird eine Fehlermeldung im folgenden For¬ 
mat ausgegeben : 

"FPU :aaaa aaaa 11:12 bbbb bbbb -- cccc cccc QU68 :dddd dddd" 
(FPU-Ergebnis,Input-Operand 1 .Input-0perand2.QU68000-Ergebnis) 

Das QU68000-Ergebnis wird per Software berechnet und mit dem FPU- 
Ergebnis verglichen. 

Tests 23..27: 

Zusatzlich zum Fehlerzahler wird ein Fehlercode (z.b. 420) mit folgender 
Bedeut'ung ausgegeben : 


Fehlerbit 

Adress-Mode 

Fehler 

o(i) 

Fx 

Daten 

1 (2) 

Fx 

Reg.Ptr. 

2(4) 

RP 

Daten 

3(8) 

RP 

Reg.Ptr. 

4 (10) 

RP+ 

Daten 

5 (20) 

RP+ 

Reg.Ptr. 

6 (40) 

RP++ 

Daten 

7 (80) 

RP++ 

Reg.Ptr. 

8(100) 

-RP 

Daten 

9(200) 

-RP 

Reg.Ptr. 

10 (400) 

—RP 

Daten 

11(800) 

-RP 

Reg.Ptr. 


Fx = FPU-Register x 
RP = Register-Pointer 


Bei Fehlei^Abbruch: 

Der gesamte Zustand des FPP wird am Bildschirm ausgegeben. d.h. es 
erfolgt ein Dump von Op-BufTer, Res-BufTer, aller FPU-Register, CSR und 
Test-Register. 
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3.4.5 Beispiele 

Laden des Testprogramms mit dem Minitor von Floppy: 

.rx 

./fpptsi 

eo 

Laden des Testprogramms mit dem Testmonitor: 
fpptst dialog 

Dialog: 

Gib Kommando [ max. 3 Zeichen ]:Ll 
Gib Kommando [ max. 3 Zeichen ]:L 2 
Gib Kommando [ max. 3 Zeichen ]:L3 
Gib Kommando [ max. 3 Zeichen ]:L15 
Gib Kommando [ max. 3 Zeichen ]:g 
Konsole [J/N]: J 
LP-Drucker[J/N] :N 

Die Tests 1,2,3, und 15 werden als Dauertest gestartet. 

Abbruch mit ~Z 

Gib Kommando [ max. 3 Zeichen ]:L31 
Gib Kommando [ max. 3 Zeichen ]:c2l 
Gib Kommando [ max. 3 Zeichen ]:c22 
Gib Kommando [ max. 3 Zeichen ]:g 
Konsole [J/N]: J 
LP-Drucker[J/N]:N 

Alle Tests mit Ausnahme von Test 21 und 22 werden als Dauertest ges¬ 
tartet. 

Abbruch mit ~Z 

Gib Kommando [ max. 3 Zeichen ]:slO 
Gib Kommando [ max. 3 Zeichen ]:s 9 
Gib Kommando [ max. 3 Zeichen ]:s20 
Gib Kommando [ max. 3 Zeichen ]:s07 
Gib Kommando [ max. 3 Zeichen ]:g 
Konsole [J/N]: j 
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LP-Drucker[J/N]:n 


Der Test 7 wird einmal 

gestartet. 

Weiter [J/N] ? : j 

(Test 9 ?) 

Weiter [J/N] ? : j 

(Test 10?) 

Weiter [J/N] ? : j 

(Test 20?) 

Weiter [J/N] ? : j 

(Test 7 ?) 

Weiter [J/N] ? : j 

(Test 9 ?) 

Weiter [J/N] ? : n 

(Test 10?) 

Gib Kommando [ max. 

PROGRAMM-ENDE 

3 Zeichen ]:e 
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1. Einleitung 

Fur den Test des LBP68000-Gesamtsystems wurde ein Standalone- 
Testprogramm entwickelt, das verschiedene Testmuster erzeugt und auf 
dem Laser-Drucker ausgibt. Damit kann die Funktion des LBP-KE und 
des Laser-Druckers sowie die Druckqualitat uberpriift werden, was 
immer nach Reparaturen, Wartungs- und Einstellarbeiten am Drucker 
erforderlich ist. 
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2. Voraussetzungen 

2.1 Dokumentation 

Diese Testanweisung setzt die Kenntnis folgender Beschreibung voraus: 

- LBP-KE Hardware/Firmware-Dokumentation 
Drucker-Service-Unterlagen: 

- CANON LBP10 Operation Manual 

- CANON LBP10 Service Handbook 

- CADMUS Testmonitor Benutzeranleitung 

2.2 Testhilfsmittel 

- QU68000-System mit Q22-Bus 

- LBP-KE Laser Printer Controller bestehend aus 

LBP-CP B907.034 mit PROM-Satz gebr. nach R900.062 
LBP-MA B922.202 (LBP10-MIKIBUS-Adapter) 

Verb.kabel K900.452 
Verb.kabel K924.302 

- 512 KByte RAM 

- DLV 11 oder Multi-Function-Board 

- Platten-, Band- oder Streamer-Laufwerk 

- Platten-, Band- oder Streamer-Controller 

- Terminal (VT100 komp.) 

- Laser Printer LBP 10 


2.3 T e stprogramm 

lbptst 
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3. Testablauf 


3.1 Testprogramm Ibptst 

Das Testprogramm Ibptst wird vom Minitor oder vom Testmonitor 
geladen und gestartet. Es meldet sich mit einem Menue der 
verfugbaren Testkommandos bzw. -Muster. 


3.1.1 Testmuster 

Gibt man die Nummer eines Testmusters ein, kommt nach einigen 
Sekunden, die der Rechner zum Aufbau des Bildes im Speicher 
braucht, die Abfrage nach der Anzahl der Kopien; nach dieser Eingabe 
sollte der Drucker anlaufen (falls nicht 3.1.4). Eine Kombination 
aller Testmuster wird mit dem Kommando "K" ausgedruckt. 


3.1.2 Statusabfrage 

Mit dem Kommando *'S" kann der Status des Laser-Druckers abgefragt 
werden, der als Hex-Code am Bildschirm ausgegeben wird (Normal: 
001BH). Zur Auswertung des Codes siehe Hardware/Firmware- 
Dokumentation. 


3.1.3 Fehlermeldungen 

Bei Auftreten bestimmter Fehler, z.b Drucker nicht selektiert, erfolgt 
eine Fehlermeldung mit Angabe des Command/Status-Register-Inhalts. 
Zur Auswertung des Codes siehe Hardware/Firmware-Dokumentation. 


3.1.4 Fehler-Diagnose 

Bleibt das Testprogramm hangen und/oder lauft der Drucker nicht an, 
kann mit Hilfe des Controller-Diagnose-Registers der Zustand des 
LBP-KE festgestellt werden. Die Zustandscodierung ist der 
Hardware/Firmware-Dokumentation zu entnehmen. Wartet z.b das 
LBP-KE vergeblich auf ein bestimmtes Signal vom Drucker, kann aus 
dem Zustandscode entommen werden. um welches Signal es sich han- 
delt. In jedem Fall sollte bei Auftreten derartiger Fehler ein INIT und 
Neustart des Testprogramms versucht werden. 
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1. Einleitung 

Mit Hilfe des Testprogramms muxketst kann das MUX-KE-Modul der Firma PCS 
getestet werden. Muxketst ist speziell auf den Prozessor QU68000 
(Q68030/50) zugeschnitten. 

2. Voraussetzung 

2.1. Hardware 

- MUX-KE Modul 

Adresse: 766000 

- 1 bis 4 DLVl 1-j 

Adressen: 776500 
776540 
776600 
776640 

- Kurzchluss-Stecker fur V24: 

output input 


s-r 

r-s 

masse-masse 


2.2. Software 

- CADMUS Testmonitor 

- Testprogramm MUXKETST 

Muxketst ist ein Standalone-Testprogramm das ohne Betriebssystem ablauft. 
Gestartet wird muxketst mit dem Testmonitor. Optional kann muxketst auch 
direkt vom Minitor geladen und gestartet werden (siehe Punkt 3). 

3. Testprogramm muxketst 

3.1. Laden und Starten des Programms vom Testmonitor 
@muxketst [param-list] 

Fur eine detailierte Beschreibung siehe MUXKETST(TM). 

3.2. Laden und Starten des Programms durch den Minitor 
.40.7fffl=000000<cr> (Optional) 

.rx (Laden von der Floppy) 

./muxketst 

.g0 (Start) 

(Der Punkt ist das Minitor-Prompt-Symbol.) 
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3.3. Programmausgabe: 

••• MUX-KETEST VOl.xx ••• 

1 : Senden 2 : Kurschluss 

L3.S3: ALL G: START Cxy: CLEAR E: EXIT 


Gib Kommando [ maximal 3 Zeichen ]: 

Die vorhandenen Tests kann man entweder als Einzel- oder Dauertest starten. 
Als mogliche Kommandos sind einzugeben: 

Sxy Einmalige Durchfiihrung des Tests xy 

S3 Einmalige Durchfiihrung aller Tests 

Lxy Test xy im Endlos-Betrieb 
L3 Endlos-Betrieb aller Tests 
Cxy Losche Test xy 
G Start 

E Riickkehr zum Testmonitor 

xy ist maximal eine zweistellige Zahl zwischen I und 2, z.B.: 

L01<cr> Dauerbetrieb fiirTest 1 
L02<cr> Dauerbetrieb fiir Test 2 
C Test 2 nicht durchgefuhrt werden 

S2<cr> Einmalige Durchfiihrung von Test 2 

Beispiel: Alle Tests im Endlos-Betrieb starten 

L3<cr> 

G<cr> 

3.4. Programmeingabe 

3.4.1. Minitor-Betrieb 

Bei Aufruf von muxketst direkt vom Minitor erfolgt die Testauswahl wie oben 
beschrieben. Besondere Parameter werden im Dialog wie beim Aufruf des 
Programmes vom Testmonitor mit dem Parameter dialog eingegeben. 

3.4.2. Testmonitor-Betrieb 


3.4.2.1. Testauswahl durch Aufruf: 

muxketst<cr> Default Test 1 und 2 

muxketst test=l<cr> nurTestl 

muxketst test=2<cr> nur Test 2 

muxketst test=l,2<cr> Test 1 und 2 

Fiir weitere Moglichkeiten siehe MUXKETST(TM). 


3.4.2.2. Dialog 

Bei Aufruf mit dem Parameter dialog fuhrt das Programm folgenden Dialog 
mit dem Bediener: 






- 4 - 


1) Konsole [J/N]?: 

J: Das Protokoll wird auf der Konsole erstellt. 

N: Kein Protokoll auf der Konsole. Diese Option ist bei HW-Messungen 
zu empfehlen. da die Testfolge schneller durchgefuhrt wird. 

2) LP-Drucker [J/N]?: 

J: Das Protokoll kann zusatzlich zur Terminal-Ausgabe auf einem 
Drucker ausgegeben werden. Bei Dauertest werden nur die Fehlermel- 
dungen ausgegeben. 

3) Gib Anzahl der Bytes: 

Hier kann man eine Zahl zwischen 0 und 255 eintippen. Diese Zahl 
gibt an, wieviele Zeichen gesendet werden sollen. 

4) Gleiches Datum [x] [J/N]?: 

J: Nur x’s werden gesendet. Das x ist ein beliebiges ASCII- Zeichen. 

N: Die Zeichen werden in aufsteigenden Form gesendet, z.B: abcdef. 

5) Gib OUTPUT channel [0..15]: 

Hier muss man die Nummer des Sendekanals eingeben. 


Kanal 0 bis 3: 
Kanal 4 bis 7: 
Kanal 8 bis 11: 
Kanal 12 bis 15: 


1. DLV11-J Modul mit der Adresse: 776500 

2. DLV11-J Modul mit der Adresse: 776540 

3. DLVll-J Modul mit der Adresse: 776600 

4. DLVll-J Modul mit der Adresse: 776640 


6) Gib INPUT channel [0..15]: 

Hier muss man die Nummer des Empfangerkanals eingeben. Siehe 5) 


3.5. Statusreport 

Tritt wahrend des Tests ein Fehler auf, wird dieser Fehler durch einen Zahler 
auf dem Bildschirm oder auf dem Drucker protokolliert. 

LOOP-COUNTER entspricht der Anzahl der Tests, die durchgefuhrt wur- 
den. 

ERROR-COUNTER gibt die Anzahl der fehlerhaften Versuche bei den 
entsprechenden Tests an. Z.B.: 

Anzeige: 1: 100 2: 300 

Interpretation: 

Test 1 hat bisher 100 fehlerhafte Versuche. Test 
2 hat bisher 300 fehlerhafte Versuche. 

3.6. Fehlermeldungen 

Fehler, die vom MUX-KE-Modul gemeldet werden (Siehe MUX-KE 
Multiterminal-Controller Beschreibung D920.221): 

Transmit error 
Parity error 
Framing error 
Data overrun 
Silo overflow 
Non existent memory 

Diese Meldungen zeigen die Anzahl der Fehler an, die wahrend des Tests 
auftreten, z.B.: 

Anzeige: Parity error: 40 

Interpretation: Es haben bisher 40 Uebertragungen mit Parity-Fehler 
stattgefunden. 
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Fehler, die der Test selbst feststellen kann: 

Receive-Timeout Hier empfangt man die Daten entweder zu 

langsam oder uberhaupt nicht. 

Send-Timeout Der Sender ist entweder zu langsam, oder 

beendet sich nicht innerhalb eines fest- 
gelegten Zeitraums. 

Too many received bytes Hier wurden mehr Zeichen empfangen als 

erwartet. 


Too less received bytes Hier wurden weniger Zeichen empfangen als 

erwartet. 

Diese Meldungen zeigen die Anzahl der Fehler an, die wAhrend des Tests 
auftreten, z.B.: 

Anzeige: Too less received bytes: 10 

Interpretation: Hier haben bisher 10 Uebertragungen mit zu wenig 
empfangenen Daten stattgefunden. 

Vergleich error gibt an, wieviele Zeichen bei einem vorangegangenen Versuch 
fehlerhaft empfangen wurden (nur bei Test 2 moglich). 


3.7. Programmabbruch 

Durch Eingabe von CTRL-C kann das Programm jederzeit abgebrochen wer- 

den. 

4. Kurzbeschreibung der Testmodule 

Sende-TEST: 

— Fur Minitor-Betrieb: (Kommandos: si, 11, s3, 13) 

— Hier werden auf einen Kanal (OUTPUT CHANNEL) nur Daten gesendet. Alle 
moglichen Sendefehler werden auf der Konsole protokolliert. 

Kurschluss-TEST: 

— Fur Minitor-Betrieb: (Kommandos: s2,12, s3,13) 

— Hier werden zuerst Daten uber einen Kanal gesendet und uber einen 
anderen empfangen. Dafur wird ein entsprechender Kurzschluss-Stecker 
zwischen beiden Kanalen benotigt. 
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1. Einleitung 

Mit Hilfe des Testprogramms dztst kann das DZVll-Modul der Firma PCS 
getestet werden. Dztst ist speziell auf den Prozessor QU68000 (Q68030/50) 
zugeschnitten. 

2. Voraussetzung 

2.1. Hardware 

- DZV11 Modul (4 oder 8 Kanale) 

Basisadresse: 0xfle040 Vektor: 0360 

- Kurzchluss-Stecker fOr V24: (DEC: H329) 


output 

input 

s- 


r- 


DTR- 

—CO.RI 

CO.RI-— 

-DTR 

masse- 

-masse 


2.2. Software 

- CADMUS Testmonitor 

- Testprogramm DZTST 

Dztst ist ein Standalone-Testprogramm das ohne Betriebssystem ablauft. 
Gestartet wird dztst mit dem Testmonitor. Optional kann dztst auch direkt 
vom Minitor geladen und gestartet werden (siehe Punkt 3). 

3. Testprogramm dztst 

3.1. Laden und Starten des Programms vom Testmonitor 
@dztst [param-list] 

Fur eine detailierte Beschreibung siehe DZTST(TM). 

3.2. Laden und Starten des Programms durch den Minitor 

.40.7fffT=000000<cr> (Optional) 

,rx (Laden von der Floppy) 

./dztst 

,g0 (Start) 

(Der Punkt ist das Minitor-Prompt-Symbol.) 

3.3. Programmausgabe: 
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••• DZV11 TEST VOl.xx ••• 

1 : Senden 2 : Kurschluss 3: Modem (DTR=>CO,RI) 
L4.S4: ALL G: START Cxy: CLEAR E: EXIT 


Gib Kommando [ maximal 3 Zeichen ]: 

Die vorhandenen Tests kann man entweder als Einzel- oder Dauertest starten. 
Als mogliche Kommandos sind einzugeben: 

Sxy Einmalige Durchfiihrung des Tests xy 

S4 Einmalige Durchfiihrung aller Tests 

Lxy Test xy im Endlos-Betrieb 
L4 Endlos-Betrieb aller Tests 
Cxy Losche Test xy 
G Start 

E Rvickkehr zum Testmonitor 

xy ist maximal eine zweistellige Zahl zwischen 1 und 3, z.B.: 

L01<cr> Dauerbetrieb fiirTest 1 
L02<cr> Dauerbetrieb fiir Test 2 
C Test 2 nicht durchgefuhrt werden 

S2<cr> Einmalige Durchfiihrung von Test 2 

Beispiel: Alle Tests im Endlos-Betrieb starten 

L4<cr> 

G<cr> 


3.4. Programmeingabe 


3.4.1. Minitor-Betrieb 

Bei Aufruf von dztst direkt vom Minitor erfolgt die Testauswahl wie oben 
beschrieben. Besondere Parameter werden im Dialog wie beim Aufruf des 
Programmes vom Testmonitor mit dem Parameter dialog eingegeben. 

3.4.2. Testmonitor^-Betrieb 

\ 

3.4.2.I. Testauswahl durch Aufruf: 


dztst<cr> 
dztst test=l<cr> 
dztst test=2<cr> 


Default Test 1, 2 und 3: 
nur Test 1 
nur Test 2 


dztst test=l,2<cr> Test 1 und 2 

Fiir weitere Moglichkeiten siehe DZTST(TM). 

3.4.2.2. Dialog 

Bei Aufruf mit dem Parameter dialog fuhrt das Programm folgenden Dialog 
mit dem Bediener: 

1) Konsole [J/N]?: 

J: Das Protokoll wird auf der Konsole erstellt. 

N: Kein Protokoll auf der Konsole. Diese Option ist bei HW-Messungen 
zu empfehlen, da die Testfolge schneller durchgefuhrt wird. 
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2) LP-Drucker [J/N]?: 

J: Das Protokoll kann zusatzlich zur Terminal-Ausgabe auf einem 
Drucker ausgegeben werden. Bei Dauertest werden nur die Fehlermel- 
dungen ausgegeben. 

3) Gib Anzahl der Bytes: 

Hier kann man eine Zahl zwischen 0 und 255 eintippen. Diese Zahl 
gibt an, wieviele Zeichen gesendet werden sollen. 

4) Gleiches Datum (xj [J/N]?: 

J: Nur x’s werden gesendet. Das x ist ein beliebiges ASCII- Zeichen. 

N: Die Zeichen werden in aufsteigenden Form gesendet, z.B: abcdef. 

3.5. Statusreport 

Tritt wahrend des Tests ein Fehler auf, wird dieser Fehler durch einen Zahler 
auf dem Bildschirm oder auf dem Drucker protokolliert. 

LOOP-COUNTER entspricht der Anzahl der Tests, die durchgefuhrt wur- 
den. 

ERROR-COUNTER gibt die Anzahl der fehlerhaften Versuche bei den 
entsprechenden Tests an. Z.B.: 

Anzeige: 1: 100 2: 300 

Interpretation: 

Test 1 hat bisher 100 fehlerhafte Versuche. Test 
2 hat bisher 300 fehlerhafte Versuche. 


3.6. Fehlermeldungen 

Fehler, die vom DZVll-Modul gemeldet werden (Siehe DZVll, Digital micro¬ 
computer interfaces handbook): 

Transmit error 
Parity error 
Framing error 
Data overrun 
Silo overflow 
Non existent memory 

Diese Meldungen zeigen die Anzahl der Fehler an, die wahrend des Tests 
auftreten, z.B.: 

Anzeige: Parity error: 40 

Interpretation: Es haben bisher 40 Uebertragungen mit Parity-Fehler 
stattgefunden. 

Fehler, die der Test selbst feststellen kann: 

Receive-Timeout 


Hier empfangt man die Daten entweder zu 
langsam oder Qberhaupt nicht. 

Der Sender ist entweder zu langsam, oder 
beendet sich nicht innerhalb eines fest- 
gelegten Zeitraums. 

Hier wurden mehr Zeichen empfangen als 
erwartet. 

Hier wurden weniger Zeichen empfangen als 
erwartet. 

Diese Meldungen zeigen die Anzahl der Fehler an, die wahrend des Tests 
auftreten. z.B.: 

Anzeige: Too less received bytes: 10 


Send-Timeout 

Too many received bytes 
Too less received bytes 
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Interpretation: Hier haben bisher 10 Uebertragungen mit zu wenig 
empfangenen Daten stattgefunden. 

Vergleich error gibt an, wieviele Zeichen bei einem vorangegangenen Versuch 
fehlerhaft empfangen wurden (nur bei Test 2 moglich). 


3.7. Programmabbruch 

Durch Eingabe von CTRLrC kann das Programm jederzeit abgebrochen wer- 

den. 

4. Kurzbeschreibung der Testmodule 

Sende-TEST: 

— Fur Minitor-Betrieb: (Kommandos: si, 11, s4, 14) 

— Hier werden auf einen Kanal (OUTPUT CHANNEL) nur Daten gesendet. Alle 
moglichen Sendefehler werden auf der Konsole protokolliert. 

Kurschluss-TEST: 

— Fiir Minitor-Betrieb: (Kommandos: s2,12, s4,14) 

— Hier werden zuerst Daten uber einen Kanal gesendet und viber einen 
anderen empfangen. Dafiir wird ein entsprechender Kurzschluss-Stecker 
zwischen beiden Kanalen benotigt. 



I 









CO 

ZD 

H 

o 

< 

o 


e 

© 

© 

3 > 

CO 

E 

© 


o» 

© 


© 

4 -* 

B 


■o 

c 

3 


C 

3 

X) 

© 

r. 

© 

n 

i 


© 

JZ 

u 

© 


ft. 

3 

«- 


jC 

© 


C- 

3 

N 


© 

3 

C 




































— J0> 

_ «3 -*X 

3 X 


CD n# O 3 

3 — -*r>o mao 

01 0 


3 3)— CO a 

— 01 3-rf03- 

o — 


> a — ft 

03800313 

33 


3 CO 3 O C 

no a o> 3 —a 

0 


CIS ft 3 

X a 3»t d 

m 


0 N 

a B 01 E 

IP 3) 


— ooa 3 

i ft a 30 —a 

tea 


* v ' Ik) IB 

B a -* i — 

•0 


N Q. — 

• O O B >*♦ 

X 


< — C C ft 

• 0300 c a 

rt 


t-* 3 B 

• DC 3 » 3 

•• 


• 0) *3 

ft c m cd a 

o 


inrxc 

« — 1 00 CD 

3 


— cd n 

CO • CO 3 



3 3 

c • • <» a 



c 

O • • CD 



CD 

c • 




a 



— 





a 

3 

to 

a 

3 CO OX 

© o 

C 

xtn 

auto 

0.3 

r -* 

CD 

3D 

31 



£ 

*3 

0 

0 TJ 

o a 

3 — 

z 

0 r 

0 —TJ 

0 — 

a 0 

0 

— 

— 


3 

2 

a 


a 

3 — 

0 3 

ft 

C 0 

-*3 O 

a 3 

3 — 

CL 

0 

— 

i 




a 

a — 

ft 3 

g a 

X 

TJTJ 

0 O — 

—• 

a a 

| 

ft 

0 

(OT> 

o 

X 

o 

c 

X o 

3 

B a 


ft 1 

X 3 O 

CD ft 

a o 

CD 

ft 

a 

—• — 

o 


3 

i 

*t30 ^ 

0 

-t» 

0 3 

ftO 3 

O O 

ft 3 

— 

0 

CC 

O 0 

3 

«t* 

a 

o 

o 

— 3 

a 

0 

TJ 0 

a o 

O 3 

a 

O 


a 

3 ft 

r» 

0 

3 

3 

3 

— ft 

0 

— 

0 3 

»t3 

ft 

a 

o 

3 

ft 

a ft 

3 


| 

0 


a a 

3 0 0 0 3 

a 

— 0 

O 

1 TJ 


X 


a 

3 a 

o 

a 

—1 


0 3 3 

— ft ft 3 

o 

O — 

3 3 

Dm 

CD 


O 

a 

C 3 


o 


3 

a 

3 

3 0 0 — 

3 

30 


0 a 

O 

M 

3 


3 1 

__ 

3 

i 


o 

C 

X V V ft o 


O 3 

O O 

< a 

O 

3 

ft 

N 

© -H 

a 


o 

C 

3 

*3 

a IQ — - — 

X 

3 

03 

— ft 

ft 



a 

3 

3 

X 

o 

3 


ft 

3 3 © 

o 

X 

O ft 

o 

1 

a. 

«t> 

3 

3 0 


o 

c 

ft 

”0 


ft — O 

3 

«■» 

3 

0 3 

□ 

0 

O 

a 

— 3 

3 

3 

ft 

O 

3 

< 

cc ft d 

-t 

0 

aa 


a 

3 

3 

ft 

n us 

0 

-♦« 


3 

O 

o 

a 

—• 


03 

O 

< 


a 

o 

3TJ 


*»• 


3 

N 

a 

o 

© 

3 

O _ 

3 


t 

0 

a 

ft o 


co 


3 

O 


3 

c 

O 

3 O 

ft 

o 


ft 

3 

3 

a 

c 


O 

a 

X 


3 

3 

ft 3 


o 

— 


ft 

CD ft 


3 


O 

a 

•— 

TJ 

«»• 


3 Q. 

t» 


0 

O 


a i 

n 



3 

o 

0 

3 

0 

0 

O 3 

C 

< 


3 


«— 

3 

0 


O 

3 

ft 

O 

3 

— 

— C 

O 

0 


ft 


o 


3 


3 


ft 

1 

ft 

a 

— 3 

3 

3 

C 



a 


ft 




O 




0O 


1 

3 



a 






3 

1 




3 



X 



ft 



CL 

0 3 

— 3 

— a 


o c 

3 C 

3 X 

ft 

n a 

a 

O 

o 

a i 

3D l 

3J0 


a a 

a a 

a TJ 


a 3 

CO 3 

CD ft 


3 

— 3 



0 O 

a o 

a o 


CL 3 

<t 3 

ft 3 


a 

a 

a 


3 • 

3 • 

3 M 


a • 

1 • 

» 


a • 

CD* 

O 


a 

C 

c 


i a 

3 a 

3 


-* a 

*D a 

TJ 


-t 3 

3 



• I 

1 



• t-» 

t-» 



3 

O 3 

33 

O 3 

— —“033 

X 

C 

0 a 

x a 

0 a 

a o a —a 

o 

a 

3 — 

a — 

3 — 

C 0.0 0 0 

3 


•a 

3 a 

•a 

o a r ft cl 

ft 

a 

ft c 

3 c 

ft c 

3 3a ft tc 

3 


3 

3 

o 

3 


3 

CL 


O 3 
3 CO 

U 

3 

I 

a 

CL 

a 

a 


3 

-*CO 


3 

CL 


ft — O I 

a» n ^ d r~ 
ft C — 0) 
CD < 03 3 
3 ID O CD 

— a 3 a 
o 3 3 r 
3(0 0 ) a cu 
ft —3 3 3 

— a x 
o a 
33 


3 

X 


c 

a 8X3 

cd 

f-X 

— c 

•U JO 

0.9 

x»o 

-H 

3a 

N 3 < 

3^ 

*a x 

CD 

a 

< r o — 

TJ 

a n 

a 

CON O 

0 — 

— c a 

a 

•• • 

c 0 a 

xa 

CD 0 — 


3 

ft 3 3 ft 

a 

0 

a 

mi o 

3 ft 

0 a a 

a 

3 O 

ft 3 

— 0 

013 0 

O 

a 

— CD -t 

— • 

— c 

XU) ft 

H* ft 

3 

ft ft 3 

XX CD ft 

— • • 

u — a 


—<3 ft 

3 

3 

• ft — V. 

n 

a 3 

—X 3 

1 1 

0 

ft 0 

o —x a 

ft 

o < c 

• U 

1 ft 

a 

TJ 

O CD 0 

3 

cc a 

0 a o 

£ ^ 

C C 

a c 

0 0 8 0 

o o 

o a o 

teo 

£ ® 

3 

3 

C o C C 

a 

i ft 

ft—3 

x — 

3 3 

3 a 

N rt—3 

3 o. 

ft 9 3 

— o 

X 

c 

c 

3 3 3 3 

3 

o a 

ft O — 

1 •• 


o o 

BftO — 

to 

a • 

V ft 

r -t* 

- 3 

a 

— -* 0 — 


3 o 

a 3 ft 

3 B 

XX 

O 3 

a a 3 ft 

X 3 

3 O 

c 

3 O 

CO 

-t 

X 8 ft X 

c 

0 X 

3 a o 

£ Ci 


3 

a 3 a o 

JO 

0 < 

3 — 

C 3 


a 


3 

— a 

ft 3 3 

Z CC 

3 3 

ft < 

O ft 3 3 

o 

ft o 

— 0 

Z 9 

— 

3 

3 C O 3 

CL 

3 3 

a i 


a o 

3 O 

3 a ft 

3 

a 3 

X CL 

— 0 

o 


a a 3 o 



a • — 

X ft 

c o 

O 3 

ft a a — 


3 

a 

X ft 

a 


c 3 n 

3D 

a 

ft 0 


X 3 

— 

a ft a a 

0 

ft 0 

— 3 

s — 

to 

O 

a s 3 

3 

o 

X Q. 

B 

O -t 

— tf) 

a ft a. 

C 

3 — 

0 • 

a 

a 

3 

X 3 —* 

O 

3 

3 a 


3 0 

a x 

«-t a 

a 

0 ft 

a 

3 

3 


O TJ ft 0 

N 


O 3 

3 

t 3 

3 a 

B 9 3 

ft 

a a 

a a 

a 


O 

3 3 3 

a 

— 

N •• 

a 

— 3 

• —• 

9 -- 

0 

CO 3 

3 0 

3 


o 

tC X 3 

a 

a 

a 

a 

CO a 

o 

— ft ft 

c 

a i 

3 

•• 


3 

— ooa 

a 

a 

a 

ft 

C 3 

X 3 

ft 

a 

3 

3 




CD -* 3 3 

o 

a 

a 

0 

3 * 

3 a 

s « 

O 





3 

c a 3 •• 

3 

a 

o 

C 


O 3 

• O 9 

3 





O 

3 3 0 


3 

3 

3 

a 

N • 

ft 3 a 

0 






— 3 

ft 


1 

—• 

3 

a 

CD a s 

3 





—— 

a o. 

a 



a 

a 

a 

con ft 






a 

3 O 

a 


C 

3 

3 

a 

cox a 






3 

a 

ft 


3 

a 


o 

CO 8ft 







3 

a 


CL 

3 


3 

te * 








3 






s 







o I I -Lai 





















































L > 

© © 

© © TJ 


£ 

© 


3 ^ 

£ TJ 

44 

0—3 

© C 

— C t- 

4- 3 

o>— 0 

44 

C 44^, 

— C 

— 44 L) UJ —■ 

c © 

LO— ©X«h 

•— H- 

E u » —« 

V. © c 

c -x> 

0 3© 

© -03M 
TJ 3 X2Q 

44 t. u 
© CL© 


N £ 

c n - 

c « 
c jo £ 
-• c c—' w 
a> © 

•-» ♦* *o 

I — £ N 

© -* 0*0 

— UlB O © 

— B • X X 

X • tu ro 

©> £ fi 

<♦* *o 

— o £ 

EC <o 


"s. L — 

w O □» 

X) — 

© © ft- 

31:3 k 
44 o 

4-*.-. X 
^LO 
u • — 

©> © 
v. 3 
X ♦* 

®~ c 

— z © 

— 3 > 
U-C © 


13 

O 


m 

© 

— c 

— © 
4- L 

© 

©3 

o L 
« t. 
CL O 
• X 


13 

© 

£ TJ 
© C 
3 

4-* 

— c 
c © 


U 3 
4- L. 

© a. 
s c 

w 0) 

£ 

© © 
33 

4-* 

c 

^LO © 
U • (. 

4^rH 0 
©> — 
3 
X — 

©— L. 

— 3 O 
ULi 


©CO 

*0 © 3 

CL N ** 

.— l o +* 
© 3 © ft- > 
30.03 

CO 44 4- I 

..CM l- C • 
£ 3 © *♦" — m 
O^- L O • 

a <•-* © © o n 

— I LTJ —*-* 
©® X 

4-.-I C C 

3 ©CM— © 

© -h © t -4 © *D 

34* © 3X L. 
♦4 N © 

•44 (_ O 44^ 3 

© i- > 3 

O DOLH^V 

♦4H- | 44 1. 

© C • I © 
C — CD *h — 
C 3 • 3© 
©©on^l 

-3-'-'VjC 


l/>~ 

. 44 

•—4 N 
X © 

Si * 

LC X3 
© © 

C>— 4-» 

LVC 
ft- © — 
O — ^ 
X u 

0 44 

© 3© 


44 V* £ 

^ O U 
U 44 l_ 
44 © D 

®^.TJ 


L. TJ 
O C 

44 © 

u © 

♦4 © « X 

— © © o 
£ — © 

•a — £ 

© ©CL) 

>J3U I 

— © E 

ft. • c © 

•o— ro 44 

C 44 © 

© > • 3 

44 « c in 

44 © I 

© •- 3 © 

— C © — 

o © l — 

■*4 44 LL. 

© © c 

© ©— X 

c 44 © .— 

© c 

H-* —3 
4 - x — 
o o c L 
ft- © 3 © 

44 £ C 44 

© u © c 

£« E 3 


C 

« 

ft- 

£ 

© 

3 

4- 

© 

3 

© 

X 

u 

« 

c*- 

« 

3*0 

— c 

44 3 

C 

© c 

44 © 

© c. 
£ £ 
© 

©*- 
£ 
© O 
© O 
I- £ 
I 

44 x 

c c 
~z> 


c 

© 

4- L 
© © 

3 TJ © 
ft- L- O— ** 

© CL 0 3 
© t_ CO © © 

3 ©•“« C —11)4-4 

£ 3 0— • t', 

— © 44 ^ «H N 

♦4 344 “0> 44 

— ©r-4 © 

3 » L-hX © 

xz 3 ©"□>►—- t_ 

44 3 JZ © 
C 44 «*- I3DD 

0'S. O C £ 
*D (J © • © 

44 © E CM C 44 
C © © © -♦* 

-- NT) L •- 

O £ 0*^ C 
3 © L U TJ © — 

C—O © --- 

ro— 1C _ O 

ou. c • ®r 

L. — © H 3 © 
© « 3*“* 

£ © O I- +* _ 
© ^— • © V. £ 

3 CO TJ U U 

© C CM +4 L. 
I.T3 — 34- © 3 
O O © 44 3\ TJ 

>11X44 ©w 


C 

© 

C TJ 
L C 
© © 
£ © 
E © 
3 L 
C 

© c 
© © 
© © 
N £ 
O O 
l- © 
O 3 


I 

ft. 

O 

> 


4-*X 
OL© I 
£ O — X 
0*0 03 

© © o c 
© X c 
44 i_ E © C 
— © © 3 © 
© © 44 t> 

O© © ft. c 

CL 3 3 3 © 
O ©CO C £ 
TJw w 


L. 

O 

44 

u 

© 

« 

» 

u • 

- ro — 

3— £ 

c a.© 

3 ® — 

2‘••5 

O O > 

c c © 


> 

£ 


ft. 

© 

TJ 

£ 
C U 
© © 
c 
c 

o © 


44 o 

X © *4 

© CH- 

© o c 

CL * r - 

C ® — 3 
— ©— N 
© 3— £ 
XCO X*-* 


TJ 

l. c 
© — 

44 « 

c 

3 ® 

W *3 

« 44 
© 44 +* 

— ft. 

— © © 

4- — — 

I TJ L 
— © 
© L C 
— © © 
0 3 3 
© 4- 

o £ 

on —. o 
> © 
© © — 
— TJ © 
TJ '*'*>'*• 


TJ 
— C 
> — 

C © 

T3 

^ ft. 
.© 
I- *o 
© o 

•*4 

c c 

3 © 

W £ 

© © 
© 4- 


£ 

© © 

— £ 
11. © 
44 

E 


© — 
orv. 
© O 
© 44 
L. © 


— «M C W *“* 

© 44 — LO 

LlI © • 
3W-4 
©-^> 
£44 

o-^x 

© O—i 

© BD 

4-v^E 


O © 

c — 
Q.TJ £ 
© O 
t- © 
© © — 
— 3 © 
TJ4-4- 


X 

X c 

S 5 

fi £ 

O O 
> 3 
© 

£ « 

O — 

3 © 

O 

« • 

C 

♦4 — 

0 © 

© 

— c 

— © ”0 
£4-1 

X OH 


3M 


•d 


c 

© 

TJ 

C 

© 

£ 

ft. 

o 

> 

x 

o 

o 


*0 

© 

£ 


I 

© 

3 

£ 

Q 


£ 

O 


© £ 
C • 


C 44 

o © 


X © 
CO© 

— © © 
TJ TJ N 
ft. O 
» C ft. 
3 >0 l 

§.£ 
44 — — 
— 03 
© © O 

Vo" 

10 X c 


c 

ft. 

X E — 

c — 

44 © 

1 B © 

© c 

0X3 

X44 

X c 

*0 

2c 

3 B © 

fZ 3*0 

© ft. 

ft. © 

ft. 

© © 

© ft. 

© 3 

© 3 

44 © 

— ft. 3 ■ 

N 

C £ 

TJ © 

O C 

— a 

TJ • 

L © 


ft. TJ« 

CL £ 

C L. 

©CL. 

O 

— © 

3 O — 

c 0 

O OL 

4- > 3 

— ft. 
© £ 

1 

1 


3 
© C 

c © 

O 3© 

— lu 

44 © o 
X £XZ 
© © 
©3 L. 

cr © 
£ » 
© 03 
3© 

c c — 

© 44 

— c — 

B 3 

L- 44£ 
£ — 

© © C 
1/1 N- 


C 

44 © 
— TJ 
© O 
£X= 
ft- 

© L. 
© 

© © 


c 44 

O — 

c — 


c — 

© © 

— £ C 
C O — 
£— B 

© ft. 
ON • 
£ *— 

O C 
LU © C 
C C 
© © £ 
© £ O 
44 © C 

— 3 ro 
©BE 
CL 3 
CL C 4- 

O— 3 
TJ © © 


X 

©« 




— © 

4-TJ 
£ — O 
O 3X2 

©x: 

C L. 

C « 
44 o a 
£ >3 
© 

44 OB 

B C — 
© 3 
E 3C 
© C — 

4 - ©cn 

© £ 
3© C 
103 — 
































vernutete Abeturzureache bzu. Verdachtt 


3 

0 


31 

0 


C 

3 


(. 

© 

3 


C 

O 

> 


o 

c 

X 

o 

*0 

N 

© 

ca 

3 

0 


■ 

3 


tn 

3 


ro n n n 
< < a a 


CM CD CM CD 

< < a a 


H U) H 

< < a 


S3 


© 

© 

0 

i- 

TJ 

T3 


C 

o 

> 


• 


0 

• 



• 



• 


X 

• 


44 

• 


mm 

e 


m 

&. 


c 

© 


0 

44 


o 

0 


0 

•—» 


0 

cn 


t- 

© 


*U 



< 



1 

c 


t- 

o 


3 

•am 


T3 



0 

o 


N 

3 


O 

i. 


im 

44 


Ql 

0 



c 


0 

•00 

• 



• 

■o 


• 

n 

• 

0 0 

• 

44 

• 

~ c 

• 

— 0 
n a 

im 

0 

0 

0 c 

0 

— 0 

• 

cn i. 

3 

CT3 

• 

0 0 

• 

T5 N 

• 

— O 

• 

— im 

• 

nQm 



• 

• 

• 

• 

• 

• 

0 

• 

O 


• 

• 

• 

• 

• 

• 

0 


C 


• 

• 

• 

• 

• 

• 

O 

a 

0 


• 

• 

• 


• 

• 

o 

a 

C 


• 

• 

• 

• 

• 

• 

0 

* 



• 

• 

• 

• 

• 

• 

* 


— 


• 

e 

• 

• 

• 

• 


• 

mm 






• 

• 

mm 

• 

• 

• 

• 

0 


CD 


CD 

2 

• 

0 

• 

e 

O 

mm 


< 

O 

• 

X 

• 

• 

o 

*■ 






u 

• 

• 

0 







0 

• 

m 

0 

o 






0 

• 

• 

tm 








• 

• 

T3 

o 






3 

• 

• 

T3 

** 






tm 

• 


0 

o 






0 

• 

ai 


im 

0 







0 

0 

CL 

im 





X 

0 

L. 

L. 

N 

0 




H 

0 

44 


3 

L. 

3 

44 

0 




1 

e-4 

*v 

0 

44 

0 

3 

T3 

0 

44 

•am- 





44 

0 

44 

o 

0 

CX 




3 

X 

3 

0 

o 

JO 

0 




a 

0 

CL 


im 

< 

im 




a 

h- 

* 

O 

0 

» 


0 

c 


Hinueieet Oie Uerte der Register, die nlcht auf der Sgetenkoneole angezeigt uerden, elnd gleich 0. 

Ee iet nlcht notuendig allee von der Suetemkoneole abzuechrelben. Oie uichtigeten Inforeationen. 
die unbedingt notiert uerden eollen. Bind nit * markiert. 





























































Bad Sector Handling 
Version 1.2 


PREFACE 

Magnetic disks are derived into seperate sectors by the controller. Due to error 
conditions some sectors might be unsuitable for read and write operations (bad 
sectors). If the number of bad sectors is below a pre-defined limit, the disk can 
still be used under the operating system MUNIX. In this case, MUNIX ensures 
that bad sectors are replaced by error-free sectors. 

During normal execution, bad sector handling is transparent to the user. It sup¬ 
ports new magnetic disks, containing bad sectors on delivery and bad sectors 
which came about as a result of continuous use. 

The following magnetic disk types are supported: Standard-RL01/02, Standard- 
RK06/07 and Standard-RM02/03/05. 
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1. INTRODUCTION 

The bad sector handling routine is divided into the following three areas: 

- Disk Organization, 

- Disk Driver, 

- Verification Programs. 



1.1 Disk Organization 

Each disk is regarded as a linear sucession of "n" sectors. The sectors are 
numbered "0" through to "n-l". A disk is divided into the following three 
areas: 

- common area, 

- reolacement sectors area, 

- bad sector information file. 

Each area may contain bad sectors. The common area is used by MUMIX for the 
definition of file systems. Bad sectors found in this area cause sectors to 
be used in the replacement area. The bad sector file contains a directory of 
all bad sectors found on the disk and a reference to the reolacement sec¬ 
tors. For each bad sector found in the replacement area, an additional sec¬ 
tor is used within this area. The bad sector file is based on a redundant 
structure, i.e. information stored in bad sectors in this area is not de¬ 
stroyed. 


1.2 Disk Driver 

There are two versions of the disk driver: the stand-alone version and 
MUMIX-version. For bad sector handling, both versions must be able to oer- 
form the following functions: 

1. Protection against unauthorized access on that Dart of the disk re¬ 
served for bad sector handling (replacement area, bad sector file). 

2. User transoarent replacement of bad sectors with reolacement sectors. 


1.3 Verification Programs 

Soecial utility orograms have been developed to check naonetic disks for bad 
sectors and to initialize the bad sector file for the individual magnetic 
disk. . ' . 

On delivery, new magnetic disks should be checked for bad sectors. Addition¬ 
al bad sectors can be generated on disks already used. In this case, the 
sector must be marked aoprooriately and the information transferred to a 
replacement sector. 
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1.4 User Information 

'..'hen usinq magnetic disks, the user (system administrator) should to adhere 
to the following approach: 

1. A new disk should be verified for bad sectors and the had sector file 
should be initialized (Verification Program). 

2. Mow the magnetic disks can be.used under the'ODeratinq system MUMIX. 

If a bad sectoV is found during operations, the following steps need to be 
taken: 

3. The information stored in the bad sector is to be transferred to a re¬ 
el acement sector (Verification Program). Tne information contained in 
the bad sector is destroyed. 

4. The user can continue to use the magnetic disk under the operating 
system MUMIX. 


1.5 Compatibility to Earlier MUMIX Releases 

P.L01/02 and P,K06/07 magnetic disks, used in earlier MUMIX releases not con¬ 
taining bad sector handlina routines (inclusive VI.4) are not comoatible 
with subsequent releases. The magnetic disks involved can be used in future, 
if the following steps are executed: 

1. safe magnetic disk contents with the operating system release used sc 
far, 

2. check magnetic disk for bad sectors, 

3. the contents are now to be written back, using the new release. 

Please note that the file sizes might be changed (see rl(4), hk(4)). 

Disk tyoes RM02/03 are comoatible if addressed via the ho-driver (RPQ4/05/ 

06 R’'.02/03 without bad sector handling). However, they can be converted in 
the way described, so that the rm-driver fitted with bad sector handling can 
be used. In this case, the contents of the magnetic disk are to be saved 
with the hn-driver, after which the contents are to be restored usinq the 
rm-driver. File sizes do not change for RH02/03 magnetic disks (see hn(4), 
rm(4)). 
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2. SPECIFICATION 


2.1 Disk Organization 

2.1.1 Division of Areas 

The maqetic disk division in common area, replacement area and bad sector 
Tile is stated in detail in the following table. 


AREA 

First 

Sector 

Last 

Sector 

No. of 
Sectors 

Total disk 

0 

n-1 

n 

Common area 

0 

D-l 

D 

Replacement area 

0 

r-1 

r-D 

Bad sector file 

r 

n-1 

nr 


The disk organization and the bad sector file structure is very similar to 
the DEC Standard 144. The size of each area is soecified in a way that the 
maximum of 126 bad sectors can be handled. Reference is also made to the 
rough division in tracks and cylinders. 

The bad sector file is, for examole, always allocated to the last track of 
the last cylinder. Due to the fact that individual disk tyns vary in track 
size (number of sectors per track), the sizes of the replacement areas and 
bad sector files are dependent on the disk type used. The structure of the 
magnetic disks currently supported is found in the following table. 


NUMBER OF SECTORS 


Disk Type 

Total 

Disk 

Common 

Area 

Replacement 

Area 

Bad Sector 
File 

RL01 

20400 

20280 

160 

40 

RL02 

40960 

40760 

160 

40 

RK06 

27126 

26972 

132 

22 

RKQ7 

53790 

53636 

132 

22 

RM02/03 

131680 

131520 

128 

32 

P.M05 

500384 

500224 

128 

32 





2.1.2 Bad Sector File 

The bad sector file is structured as follows: 

--+ 


Sector 

Contents : 

0 

•bad sector information : 

1 


2 

not used : 

3 


4 

cooy from Q, I 

5 


•5 

not used : 

7 


8 

copy from 0, 1 : 

9 


10 

not used : 

11 : 

12 

copy from 0, 1 

13 


14 

not used : 

15 : 

16 

copy from 0, 1 : 

17 : 

18 

not used : 

19 : 

+--- 
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The oad sector information consists of 256 16-bit words: 


: Hord Contents : 

: 0 0 ! 

: 1 0 i 

: 2 Number of bad sectors : 

: 3 0 

: 4 Sector number : 1st bad sector entry 

! 5 I 

: 6 Sector number : 2nd bad sector entry 



: 252 Sector number : 125th bad sector entry 

: 253 : 

: 254 Sector number : 126th bad sector entry 

: 255 : 

--- 


The bad sector table containing sector numbers Is named "bad sector table". 
Unused bad sector elements are filled with "-1". On each magnetic disk there 
are five copies of the bad sector table available. A disk can be used at any 
time if one of the copies does not contain bad sector entries and no more 
than 126 bad sectors are found on the disk. 


2.1.3 Allocation: Bad Sector • Replacement Sector 

The allocation " bad sector - replacement sector" is determined by the 
sequence of entries found in the bad sector table: 

The last sector available In the replacement area (sector number r-1) is 
allocated to the first bad sector found (1st bad sector entry); the last 
replacement sector but 1 (r-2) is allocated to the second bad sector • 
found, etc. 
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2.1.4 Allocation: Sector Number - MUNIX Blocknumber 

-.UNIX data blocks are 1024 bytes long, whereas disk sectors are 256 bytes 
(RL01/02) or 512 bytes (RK06/07, RM02/03/05) long. Therefore, a MUNIX block 
spans 2 to 4 sectors. 

The stand-alone driver considers a disk as a linear succession of blocks, 
numbered <J to n/4-1 or n/2-1 (n « number of disk sectors). The allocation Is 
(dependent on the sector size): 

Sector Size Clock Number Sector Number(s) 


256 bytes a 4*a - 4*a+3 

512 bytes- a 2*a - 2*a+l 

Uhen using MUNIX, a disk can be subdivided Into a number of file systems. 

The file system blocks are numbered sequentially, relative to the first 
block of the file system (starting with 0). The absolute block number "a" of 
a particular block within a given file system Is calculated by adding all 
blocks allocated to prior file systems (offset) as well as the relative 
block number within this file system (r). By taklnq the absolute block num¬ 
ber “a", the user receives the allocated sector number (see table above). 


2.2 Verification Programs 

The verification programs are responsible for the following tasks: 

- find all bad sectors on a disk, 

- generate the bad sector table and Initialize the bad sector file on 
di sk. 

A test run needs to be performed on disk, in order to find the bad sectors. 


2.2.1 Sector Test 

The following types of sector tests are available: 

1. Write/Read processing cycle with subsequent comparison operations. 

If an error is indicated by the disk controller, the write/read opera¬ 
tion is not repeated. A sector is regarded as "bad", if a write/read 
error is detected or the comparison result is found to be negative. If 
possible, the header of the Individual sector is narked accordingly. 

2. Ootionally, a sector test is oossible using the "read-only-mode". In 
this case the disk content is not overwritten. After a read error is 
detected, the relevant sector is declared "bad". 

The bad sector table is generated at will. New bad sector entries are added 
to the end of the table. Since the sequence of entries also indicates the 
allocation of replacement sectors, it is oossible in this wav to enter bad 
sector table entries subsequently. The sequence of "old" had sectors is not 
changed. 
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2.2.2 Test Runs 

Verification programs provide a number of functions: 

1. Complete test (bad sector scan): 

The complete disk is tested. In the first step, all sectors are over¬ 
written in ascending order with the DEC test oattern “0xed6db6db". In 
the second step, all sectors are read in reverse order. The read and 
write operations are performed on complete tracks. If an error is 
found, each sector is tested individually and the bad sector is deter¬ 
mined. In this operation, the bad sector file is generated and written 
to disk, when the test is terminated. 

Functions 2 to 4 assume that the bad sector file is already available on 

di sk. 

2. Partial test: 

A contiguous number of sectors (specifications are entered in dialogue 
mode) are tested. Prior to the actual test, the bad sector file is 

read. Alternating continuously (first sector, last sector, second sec¬ 

tor, last but one sector, ...) the sectors are tested with a random 
pattern. During the test operation some new entries might be put into 
the bad sector table, in which case the table Is written back to the 
bad sector file prior to terminating the test program. 

3. Manual entries of bad sectors: 

If a disk Is used frequently and bad sector develop during normal 
usage, in some cases the verification program is not able to detect 
all bad sectors. This function helps to Identify such cases. The bad 
sector file is read and the user enters the numbers of the bad sectors 
involved. The sectors are marked "bad", and the sector identifications 
are entered in the bad sector table. Subsequently the bad sector table 
is written back onto disk. 

4. Listing all known bad sectors: 

The bad sector file is read and the identification numbers of all bad 
sectors known are listed. 

A further function is available for extented tests: 

5. Random sector test: 

A random character generator produces a sequence of sector numbers. 

The sectors addressed by these numbers are tested, using the random 
pattern generated by the test program. 

The test runs on a continuing basis but can be terminated with a'"bus 
reset". 

Attention: If a bad sector file is stored on disk, the file may be 
destroyed. 
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2.3 Disk Driver 

The general approach of both stand-alone and MUMIX driver are sir.iilar: 

Normal write/read access operations are performed as long as no bad 
sector is detected. (Bad sector detection is dependent on the disk 
type used; further details are found below.) 

If the bad sector table has not yet been read (initialization status 
or disk change), it is now read into memory. If the sector is marked 
"bad", the system accesses the relevant replacement sector. If the 
following message is displayed on the system console: disk error. 

Bad sector detection: 

a) The sector is marked "bad" in the header (e.g. RK0o/07, RM02/03/05): 

In a write/read operation, the disk controller oroduces an error mess¬ 
age. Each time the System tries to access a bad sector the controller 
answers with an error message, causing the driver to access the rele¬ 
vant replacement sector. 

b) The sector cannot be marked in the header (e.g. RL01/02): 

In order to avoid writing on a sector while not being able to read it 
without error, access to bad sectors are not allowed on principle. 
Prior to a write/read operation, the bad sector table Is checked to 
find out if the required sector is marked “bad". In this case, the 
system immediately accesses the replacement sector. 

This approach assumes that the bad sector table is read into memory 
prior to the first disk access or immediately after a disk is ex¬ 
changed. 

The stand-alone driver is different to MUMIX drivers, in that the first disk 
access reads the bad sector table. For this reason, the stand-alone program 
is to be restarted immediately after a disk is exchanged. Operating under 
MUMIX however, disks can be exchanged at any time without re-booting the 
system. 
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Abstract 

Magnetplatten werden vom Controller in elnzelne Sektoren unterteilt. Ein Teil 
dieser Sektoren kann unbrauchbar sein (bad sectors). Liegt die Anzahl der bad 
sectors unter einer bestimmten Obergrenze, kann die Platte trotzdem unter 
MUNIX verwendet werden. MUNDC sorgt in diesem Fall daf&r, dass bad sectors 
durch Ersatzsektoren ersetzt werden. 

Dieses bad sector handling ist w&hrend des normalen Betriebs fQr den Benutzer 
transparent. Es unterstUtzt sowohl fabrikneue Platten mit bad sectors als auch 
Platten bei denen w&hrend des Betriebs neue bad sectors entstehen. 

Zur Zeit werden folgende Plattentypen unterstiitzt: 

Standard-RLOi/02, Standard-RK06/07 und Standard-RM02/03/05. 


Autoren-Kennzeichen: RW 

Eingetragene Warenzeichen: 

MUNIX, CADMUS von PCS 

DEC, PDP von DEC 

UNIX von Bell Laboratories 


Copyright 1984 by 
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Die Vervielfaltigung des vorliegenden Textes, auch auszugsweise ist nur mit ausdrQcklicher 
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WLr sind bestrebt, immer auf dem neuesten Stand der Technologie zu bleiben. Aus diesem 
Grunde behalten wir uns Anderungen vor. 
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1. Emfuhrvmg 

Das bad sector handling teilt sich auf in drei Teilbereiche: 

— Plattenorganisation 
— Disk-Check-Programme 
— Plattentreiber 

1.1. Plattenorganisation 

Jede Platte wird als lineare Folge von n Sektoren betrachtet. Die Sek- 
toren sind voh 0 bis n-J durchnumeriert. Eine Platte wird in drei Bereiche 
eingeteilt: 

— oflentlicher Bereich 

— Bereich fOr Ersatzsektoren 

— bad sector Information (bad sector file) 

Jeder dieser Bereiche darf bad sectors enthalten. Der offentliche 
Bereich wird unter MUNDC fur das Anlegen von Filesystemen verwendet. Fur 
bad sectors in diesem Bereich werden im Ersatzbereich Sektoren belegt 
(Auslagemng). Das bad sector file enthait ein Verzeichnis aller bad sectors 
der Platte und die Verweise zu den Ersatzsektoren. Fur einen bad sector im 
Ersatzbereich wird ein weiterer Sektor in diesem Bereich belegt. Das bad sec¬ 
tor file ist redundant aufgebaut, so dass bad sectors in diesem Bereich in der 
Regel die benotigte Information nicht vemichten. 

1SL Plattentreiber 

Ein Plattentreiber existiert in zwei Versionen: Standalone-Version und 
MUNIX- Version. Beide Versionen mussen fur das bad sector handling folgende 
Funktionen gewahrleisten: 

a) Schutz des fur das bad sector handling reservierten Teils der Platte 
(Ersatzbereich. bad sector file) vor unberechtigtem Zugrifl. 

b) Fur den Benutzer transparente Ersetzung von bad sectors durch ihre 
Ersatzsektoren. 

1J3. Disk-Check-Programme 

Spezielle Dienstprogramme ubernehmen die Aufgabe. eine Platte auf bad 
sectors zu fiberpr&fen und das bad sector file dieser Platte zu initialisieren. 

Bei fabrikneuen Platten muss die gesamte Platte auf bad sectors 
uberpruft werden. Bei bereits beschriebenen Platten bei denen ein weiterer 
bad sector festgestellt wird. muss dieser entsprechend markiert und aus- 
gelagert werden, ohne dass die restliche Information auf der Platte zerstort 
wird. 


August 23, 1983 
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1.4. Benutzersicht 

Der Benutzer (Systemverwalter) hat beim Einsatz einer Platte folgender- 
massen vorzugehen: 

1) Uberprufung einer neuen Platte auf bad sectors und Imtialisierung des 
bad sector files (Disk-Check-Programm) 

2) Benutzung der Platte unter MUNDC 

und falls ein weiterer bad sector wahrend des Betriebs auftritt: 

31 Auslagerung des bad sectors in den Ersatzbereich (Disk-Check- 
Programm). Die Information, die der bad sector enthielt, ist zerstort. 

4) Weitere Benutzung der Platte unter MUNIX. 

1.5. Kompatibilitat zu fruheren HUNIX-Releases 

RL01/02- bzw. RK06/07-Platten, die unter einer fruheren MUNDC-Release 
ohne bad sector handling (bis einschl. Vl.4) in Gebrauch waren, and mcht 
kompatibel zu den nachfolgenden Releases. Man kann diese Platen weiterhin 
ver^enden, wenn der Inhalt der Platte mit der bishengen Release gerettet. 
die Platte auf bad sectors fiberpruft und der Inhalt mit der neuen Release 
wiederhergestellt wird. Es ist zu beachten, dass sich die Filesystem-Grossen 
eventuell andern (siehe ri(4) % hk(4)). _ 

RM02/03-Platten sind weiterhin kompatibel, *enn sie fiber den hp- 
Treiber (RP04/05/06, RM02/03 ohne bad sector handling) angesprochen wer- 
2ie kdnnen jedoch in der geschilderten Art und Weise auf den rm - 
Treiber mit bad sector handling umgestellt werden. Dazuist der Inhalt einer 
Platte mit dem hp-Treiber zu retten und mit dem rm-Trexber wiederherzustel- 
len. Die Filesystem-Grossen Andern sich bei RM02/03-Platten mcht (siehe 

hp (4), rm (4)). 
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2. Spezifikation 

2.1. Plattenorganisation 

2.1.1. Einteilung in Bereiche 

Die Einteilung einer Platte in offentlicher Bereich, Ersatzbereich und bad 
sector file ergibt sich aus nachstehender Tabelle. 


Bereich 

erster Sektor 

letzter Sektor 

Sektorzahl 

gesamte Platte 

0 

n-1 

n 

ofTentlicher Bereich 

0 

p-i 

p 

Ersatzbereich 

P 

r-1 

r-p 

bad sector file 

r 

n-1 

n-r 


Die Plattenorganisation und der Aufbau des bad sector file lehnt sich eng 
an den DEC Standard 144 an. Die Grosse der einzelnen Bereiche wird fur die 
Behandlung von bis zu 126 bad sectors ausgelegt. Dabei wird auch auf die 
Grobeinteilung einer Platte in Spuren und Zylinder Bezug genommen. 

Das bad sector file liegt z. B. immer auf der letzten Spur des letzten Zylinders. 
Ebenfalls umfasst der Ersatzbereich inuner mehrere komplette Spuren. Da bei 
verschiedenen Plattentypen die Spurgrosse (Anzahl Sektoren pro Spur) vari- 
iert, sind die Grossen des Ersatzbereiches und bad sector files abhangig vom 
Plattentyp. Die Aufteilung bei den zur Zeit unterstutzten Plattentypen ist der 
folgenden Tabelle zu entnehmen 



Anzahl der Sektoren 

Plattentyp 

gesamte 

SfTentlicher 

Ersatz¬ 

bad sector 

Platte 

Bereich 

bereich 

file 

RL01 

20480 

20280. 

160 

40 

RL02 

40960 

40760 

160 

40 

RK06 

27126 

26972 

132 

22 

RK07 

53790 

53636 

132 

22 

RM 02/03 

131680 

131520 

128 

32 

RM05 

500384 

500224 

128 

32 


2.1J2. Bad Sector File 

Das bad sector file besitzt folgenden Aufbau: 
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Sektor 

Inhalt 

0 

1 

bad sector Information 

2 

nicht benutzt 

3 


4 

Kopie von 0,1 

5 


6 

nicht benutzt 

7 


6 

Kopie von 0,1 

9 


10 

nicht benutzt 

11 


12 

Kopie von 0,1 

13 

' 

14 

nicht benutzt 

15 


16 

Kopie von 0,1 

17 


18 

nicht benutzt 

19 



Die bad sector Information besteht aus 256 16 -Bit-Worten: 


Wort T 

Tnhalt 

0 

0 

1 

0 

2 

Anzahl bad sectors 

3 

0 

4 

Sektornummer 

5 


6 

Sektornummer 

7 


• 

• 

252 

Sektornummer 

253 


254 

Sektornummer 

255 



1. bad sector 

Eintrag • 

2. bad sector 

Eintrag 


125. bad sector 

Eintrag 

126. bad sector 

Eintrag 


Die Tabelle der bad sector - Sektomummem heisst bad sector table. 
Unbenutzte bad sector Eintrage werden mit "-1" aufgefullt. Die bad sec or 
table wird in funffacher Kopie auf einer Platte abgespeichert, Eine Platte is 
^er^endbar, wenn eine dieser Kopien bad-sect or- frez ist und die 
Gesamtzahl der bad sectors 126 nicht ubersteigt. 
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2.1.3. Zuordnung: Bad Sector — Ersatzsektor 

Die Zuordnung bad sector — Ersatzsektor ergibt sich aus der Reihenfolge 
der Eintrage in der bad sector table: 

Dem ersten erfassten bad sector (1. bad sector Eintrag) wind der letzte 
Sektor im Ersatzbereich zugeordnet (Sektomummer r-1) dem 2. der vor- 
letzte Sektor im Ersatzbereich (r-2) , usw. 

2.1.4. Zuordnung: Sektomummer — IfUNIX-Blocknummer 

MUNDC-Blocke sind 1024 bytes gross, Plattensektoren 256 (bei RL01/02) 
oder 512 bytes (RK06/07, RM02/03/05). Ein MUNIX-Block umfasst somit 4 
bzw. 2 Sektoren. 

Die Standalone-Treiber betrachten eine Platte als lineare Folge von 
Blocken mit den Nummera 0 bis n/4-1 bzw. n/2-1 (n = Anzahl der Sektoren 
einer Platte). Die Zuordnung lautet (abhangig von der Sektorgrosse): 


Sektorgrosse 

Blocknummer 

Sektomummer(n) 

256 bytes 

a 

4*a — 4*a+3 

“512 bytes 

a 

2*a — 2*a+l 


Unter MUNDC kann eine Platte in mehrere Filesysteme unterteilt werden. 
Die Blocke eines Filesystems werden relativ zum ersten Block des Filesystems 
durchnumeriert (beginnend mit 0). Die absolute Blocknummer a des Blocks 
eines Filesystems ergibt sich aus der Summation der Blocke der vorhergehen- 
den Filesysteme (offset) plus der relativen Blocknummer r. Aus der absoluten 
Blocknummer a erhalt man die zugeordneten Sektomuromem fiber die 
vorstehende Tabelle. 

2J2. Disk-Check-Programme 

Aufgabe der Disk-Check-Programme ist es 

— alle bad sectors auf einer Platte zu finden 

— die bad sector table aufzubauen und das bad sector file-auf der Platte 
anzulegen. 

Das Auffinden der bad sectors erfolgt dtirch Testen der Plattensektoren. 
2:2.1. Sektortest 

Beim Sektortest wird folgendermassen vorgegangen: 

1) Schreib-/Lese-Zyklus mit anschliessendem Datenvergleich. 

Der Schreib- bzw. Lesezugriff wird nicht wiederholt, wenn vom Platten- 
controller ein Fehler angezeigt wird. Ein Sektor wird als bad betra- 
chtet bei einem Schreib-/Lesefehler oder falls der Vergleich Unter- 
schiede erbringt. Falls moglich, erfolgt eine entsprechende Mar- 
kierung im Header des Sektors. 

2) "Wahlweise ist ein Sektortest im Read-Only-Modus moglich, um den 
lnhalt einer Platte nicht zu zerstSren. In diesem Fall wird nach einem 
Lesefehler der Sektor als bad betrachtet. 

Der Aufbau der bad sector table erfolgt ungeordnet. Neue bad sectors 
werden ans Ende der Tabelle angefugt. Da sich aus der Reihenfolge der 
Eintrage die Zuordnung zu den Ersatzsektoren ergibt, kann auf diese Weise 
auch nachtraglich ein neuer bad sector in die Tabelle aufgenommen werden. 
An der Reihenfolge der "alten” bad sectors Sndert sich dadurch nichts. 
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2.2.2. Testablaufe 

Die Disk-Check-Pro gramme stellen verschiedene Funktionen zur 
Verfiigung: 

0 me'ko^feUe'BaS^ww'^eVestet. Die Sektoren »”den zueret in 
aufsteieender Ordnung mil dem DEC-Testmuster taebSdbedb 
beechrfeben. Anschliessend werden die Sektoren in abste,gender , 
Ordnung gelesen. Auf die Sektoren wird dabei m grosseren Emheiten 
vjrunuiig 6 Snur > Tritt dabei ein Fehler auf, wird der 

Zugrfff 1 tor jeden Sektor einzeln wiederholt und der bad sector fest- 
gestellt. Dabei wird das bad sector file aufgebaut und nach Abschluss 
{jgs Tests &uf die Plette gcschricbcn. 

Die Funktionen 2) bis 4) setzen voraus. dass auf der Platte bereits em 
bad sector file existiert. 

Ein^rusanOTenhangende Folge von Sektoren (im Dialog spezifiziert) 
wird getestet. Vor diesem Test wird das bad sector file gelesen. Die 
Sektoren werden alternierend (1. Sektor, letzter Sektor, 2. ^ ekt ° T - —) 
mit einem Random-Muster getestet. Beim Test werdi e “ *1* secto/file 
bad sectors eingetragen und anschliessend das bad sector file 

zuruckgeschrieben. 

Manuelles Elntragen von bad sectors: , 

Bad sectors, die erst nach langerer Benutzung einer Platte entstehen. 
werden von den Disk-Check-Programmen nicht in_ alien Pallenj-egistn- 
ert. Diese Funktion dient zur Kennzeichnung solcher bad sectors. 

Das bad sector file wird gelesen. Der Benutzer gibt die Nummern von 
bad sectors ein. Diese Sektoren werden als bad markiert und in die 
bad sector table aufgenomroen. AnschUessend wird das bad sector file 
zuruckgeschrieben. 

4) Auflisten aller bekannten bad sectors: 

4 Das bad sector file wird eingelesen. Die Nummern aller bad sectors 
werden aufgelistet. 

Fur einen Langzeittest steht eine weitere Funktion zur Verfugung: 

Eh^'zufallsgenerator erzeugt eine Folge von Sektomummem. Diese 
Sektoren werden mit einem Random-Muster getestet. , 

Der Test ist nicht terminiert. Er kann durch einen Bus-Reset abgebro- 

nnvoT'hi'denzs bad sector Me aul der Platte wird eventuell aerstort. 


2.3. Plattentreiber .. , , 

Die generelle Vorgehensweise ist beim Standalone-Treiber und beim 

MUNK-Treiber ahnlich: 

Es werden solange Schreib-/Lesezugrifle auf die Platte ausgefuhrt, bis 
auf einen bad sector zugegriflen wird. (Die bad sector Erkennung kann 
vom Plattentyp abhangig sein; sie wird weiter unten skizziert.) 

Fans cSe bad P sector 8 tfble noch nicht von der Platte gelesen wurde 
(Anfangszustand bzw. nach Plattenwechsel). wird sie nun eingelesen. 1st 
der Sektor als bad markiert, wird auf den zugeordneten Ersatzsektor 
ligegriflen (rekursiv!). Andernfalls erfolgt eine Meldung auf die System 

konsole: disk error. 


August 23, 1983 




-7- 


Erkennen von bad sectors: 

o) Moa/ot/Ss): isl im Header als bad ■ Mrkiert < 2 ' B - RK06/07. 

Der Plattencontroller erzeugt eine Fehiermeldung bei einer Schreib- 
/Leseoperation. Jeder Versuch auf einen als bad markierten Sektor 

V ° m Controller nit einer Fehiermeldung quittie" 
auf die der Treiber mit einem ZugrifT auf den Ersatzsektor reagiert. 

b) Der Sektor kann nicht im Header markiert werden (z.B. RL01/02V 

ShaIh£S5 rn ’) daSS Cin ! ekt ° r fehlerf rei beschrieben, jedoch 
nicht fehlerfrei gelesen werden kann, wird ein ZugrifT auf bad sectors 

von vorneherein ausgeschlossen. Vor einer Schreib-/Leseoperation 

wird die bad sector table inspiziert, ob der betrofTene Sektor als bad 

zugegrifTerf*” ±SSem FaIle wird sofort au ^ den Ersatzsektor 

Kil Se J°? ehenSW o e , ise 5BtZt voraus * dass vor ersten PlattenzugrifT 
bzw. nach einem Plattenwechsel die bad sector table eingelesen wird. 

, j ^ v ^tandalone-Treiber unterscheiden sich von den MUNDC-Treibem 
dadurch, dass generell als erster PlattenzugrifT die bad sector Uble 
eingelesen wird. Nach einem Plattenwechsel ist deshalb ein Standalone- 
Programm neu zu starten. Unter HUNK konnen dagegen beliebige Plat¬ 
tenwechsel erfolgen, ohne das System neu zu booten. 
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This document describes a set of easy-to-use macros for preparing documents 
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Typing Documents on the UNIX System: 

Using the —ms Macros with Troff and Nroff 

U. £ Lesk 

Bell Laboratories 
Murray Hill, New Jersey 07974 

Introduction. This memorandum describes a package of commands to produce papers 
using the troff and nroff formatting programs on the UNIX system. As with other ro^derived 
programs, text is prepared interspersed with formatting commands. However, this package, 
which itself is written in troff commands, provides higher-level commands than those provided 
with the basic troff program. The commands available in this package are listed in Appendix A. 

Text Type normally, except that instead of indenting for paragraphs, place a line reading 
“.PP” before each paragraph. This will produce indenting and extra space. 

Alternatively, the command .LP that was used here will produce a left-aligned (block) para¬ 
graph. The paragraph spacing can be changed: see below under “Registers.” 

Beginning. For a document with a paper-type cover sheet, the input should start as fol¬ 
lows: 

(optional overall format .RP - see below] 

.TL 

Title of document (one or more lines) 

.AU 

Author (s) (may also be several lines) 

.Al 

Author's institution (s) 

.AB 

Abstract; to* be placed on the cover sheet of a paper. 

Line length is 5/6 of normal; use .11 here to change. 

.AE (abstract end) 

text... (begins with .PP. which see) 

To omit some of the standard headings (e.g. no abstract, or no author’s institution) just omit 
the corresponding fields and command lines. The word abstract can be suppressed by writing 
“.AB no” for ‘\AB”. Several interspersed .AU and .Al lines can be used for multiple authors. 
The headings are not compulsory: beginning with a .PP command is perfectly OK and will just 
start printing an ordinary paragraph. Warning: You can’t just begin a document with a line of 
textf Some —ms command must precede any text input. When in doubt, use XP to get 
proper initialization, although any of the commands .PP, .LP, .TL, .SH, .NH is good enough. 
Figure 1 shows the legal arrangement of commands at the start of a document. 

Cover Sheets and First Pages. The first line of a document signals the general format of 
the first page. In particular, if it is ’.RP" a cover sheet with title and abstract is prepared. The 
default format is useful for scanning drafts. 

In general —ms is arranged so that only, one form of a document need be stored, contain¬ 
ing all information; the first command gives the format, and unn ec essa r y items for that format 
are ignored. 

Warning: don’t put extraneous material between the .TL and .AE commands. Processing 
of the titling items is special, and other data placed in them may not behave as you expect. 
Don’t forget that some —ms command must precede any input text. 
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Paze headings. The -ms macros, by default, will print a page heading containing a page 
number (if greater than l). A default page footer is provided only in nroff, where the date is 
used. The user can make minor adjustments to the page headings/footings by redefining the 
strinas LH CH. and RH which are the left, center and right portions of the page headings, 
respectively; and the strings LF. CF. and RF. which are the left center and nght pornons of 
the page footer. For more complex formats, the user can redefine the macros PT and BT, 
which are invoked respectively at the top and bottom of each page. The margins (taken from 
registers HM and FM for the top and bottom margin respectively) are normally 1 inch; the page 
header/footer are in the middle of that space. The user who redefines these macros should be 
careful not to change parameters such as point size or font without resetting them to default 


values. 

Multi-column formats. If you place 
the command “.2C” in your document, the 
document will be printed in double column 
format beginning at that point. This feature 
is not too useful in computer terminal out¬ 
put. but is often desirable on the typesetter. 
The command “.1C* will go back to one- 
column format and also skip to a new page. 
The “2C” command is actually a special 
case of the command 

.MC (column width (gutter widthll 

which makes multiple columns with the 
specified column and gutter width; as many 
columns as will fit across the page are used. 
Thus triple, quadruple, ... column pages can 
be printed. Whenever the number of 
columns is changed (except going from full 
width to some larger number of columns) a 
new page is started. 

Headings. To produce a special head¬ 
ing, there are two commands. If you type 

.NH 

type section heading here 

may be several lines 


Care and Feeding of Directors 

Every section heading, of either type; 
should be followed by a paragraph beginning, 
with .PP or .LP, indicating the end of the 
heading. Headings may contain more than 
one line of text. 

The .NH command also supports more 
complex numbering schemes. If a numeri¬ 
cal argument is given, it is taken to be a 
“level” number and an appropriate sub¬ 
section number is generated. Larger level 
numbers indicate deeper sub-sections, as in 
this example: 

.NH 

Erie-Lackawanna 

.NH 2 

Morris and Essex Division 

.NH 3 

Gladstone Branch 

.NH 3 

Montclair Branch 

.NH 2 

Boonton Line 
generates: 


you will get automatically numbered section 
headings (l, 2, 3, ...), in boldface. For 
example. 


2. Erie-Lackawanna 

2.1. Morris and Essex Divisioo 


.NH 

Care and Feeding of Department Hea d s 


2.1.1. Gladstone Branch 


produces 

1. Care and Feeding of Department Heads 

Alternatively, 

.SH 

Care and Feeding of Directors 

will print the heading with no number 
added: 


2.1.2. Montclair Branch 

2.2. Boonton Line 

An explicit “.NH 0” will reset the 
numbering of level l to one, as here: 

.NH 0 

Penn Central 


1. Penn Central 
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Indented paragraphs. (Paragraphs 
with hanging numbers, c.g. references.) The 
sequence 

.IP (1) 

Text for first paragraph, typed 
normally for as long as you would 
like on as many lines as needed. 

OP [21 

Text for second paragraph e ••• 
produces 

tl] Text for first paragraph, typed nor* 
mally for as long as you would like on 
as many lines as needed. 

(2] Text for second paragraph % ••• 

A series of indented paragraphs may be fol¬ 
lowed by an ordinary paragraph beginning 
with .PP or .LP, depending on whether you 
wish indenting or not. The command .LP 
was used here. 

More sophisticated uses of .IP are also 
possible. If the label is omitted, for exam* 
pie, a plain block indent is produced. 

JP 

This material will 

just be turned into a 

block indent suitable for quotations or 

such matter. 

J.P 

will produce 

This material will just be turned into a 
block indent suitable for quotations or 
such matter. 

If a non-standard amount of indenting is 
required, it may be specified after the label 
Cm character positions) and will remain in 
effect until the next .PP or .LP. Thus, the 
general form of the .IP command contains 
two additional fields: the label and the 
indenting length. For example, 

JP first: 9 

Notice the longer label, requiring larger 
indenting for these paragraphs. 

.IP second: 

And so forth. 

.LP 

produces this: 


first: Notice the longer label, requiring 

larger indenting for these para¬ 
graphs. 

second: And so forth. 

It is also possible to produce multiple nested 
indents; the command .RS indicates that the 
next .IP starts from the current indentation 
level. Each .RE will eat up one level of 
indenting so you should balance .RS and 
.RE commands. The .RS command should 
be thought of as “move right“ and the .RE 
command as “move !eft“. As an example 

.IP 1. 

Bell Laboratories 

.RS 

.IP 1.1 

Murray Hill 

.IP 1.2 

Holmdei 

.IPU 

Whippany 

.RS 

.IP 1.3.1 

Madison 

.RE 

JP 1.4 

Chester 

.RE 

.LP 

will result in 
l. Beil Laboratories 

1.1 Murray Hilt 

1.2 Holmdei 

1.3 Whippany 
1.3.1 Madison 

1.4 Chester 

Ail of these variations on .LP leave the right 
margin untouched. Sometimes, for pur¬ 
poses such as setting off a quotation, a para¬ 
graph indented on both right and left is 
required. 

A single paragraph like this is 
obtained by preceding it with 
.QP. More complicated material 
(several paragraphs) should be 
bracketed with .QS and .QE. 

Emphasis. To get italics (on the typesetter) 
or underlining (on the terminal) say 





-4- 


.1 . 

as much text as you want 

can be typed here 

.R 

as was done for these three words. The .R 
command restores the normal (usually 
Roman) font. If only one word is to be ital¬ 
icized, it may be just given on the line with 
the .1 command, 

.1 word 

and in this case no .R is needed to restore 
the previous font. Boldface can be pro¬ 
duced by 

• .R 

Text to be set in boldface 

goes here 

.R 

and also will be underlined on the terminal 
or line printer. As with .L a single word can 
be placed in boldface by placing it on the 
same line as the .B command. 

A few size changes can be specified 
similarly with the commands .LG (make 
larger). .SM (make smaller), and .NL 
(return to normal size). The size change is 
two points; the commands may be repeated 
for increased «oa (here one .NL canceled two 
.SM commands). 

If actual underlining as opposed to ital¬ 
icizing is required on the typesetter, the 
command 

.UL word 

will underline a word. There is no way to 
underline multiple words on the typesetter. 

Footnotes* Material placed between 
lines with the commands .FS (footnote) and 
.FE (footnote end) will be collected, 
remembered, and finally placed at the bot¬ 
tom of the current page*. By default, foot¬ 
notes are Il/I2th the length of normal text, 
but this can be changed using the FL regis¬ 
ter (see below). 

Displays and Tobies. To prepare 
displays of lines, such as tables, in which the 
lines should not be re-arranged, enclose 
them in the commands .DS and .DE 


.DS 

table lines, like the 
examples here, are placed 
between .OS and .DE 
.DE 

By default, lines between .DS and .DE are 
indented and left-adjusted. You can also 
center lines, or retain the left margin. Lines 
bracketed by .DS C and .DE commands are 
centered (and not re-arranged); lines brack¬ 
eted by .DS L and .DE are left-adjusted, not 
indented, and not re-arranged. A plain .DS 
is equivalent to .DS L which indents and 
left-adjusts. Thus, 

these lines were preceded 
by .DS C and followed by 
a .DE command; 

whereas 

these lines were preceded 
by .DS L and. followed by 
a .DE command. 

Note that .DS C centers each line; there is a 
variant .DS B that makes the display into a 
left-adjusted block of text, and then centers 
that entire block. Normally a display is kept 
together, on one page. If you wish to have 
a long display which may be split across page 
boundaries, use .CD, .LD, or .ID in place of 
the commands .DS C, .DS L, or .DS I 
respectively. An extra argument to the .DS 
I or .DS command is taken as an amount to 
indent. Note: it is tempting to assume that 
.DS R will right adjust lines, but it doesn’t 
work. 

Boxing words or lines: To draw rec¬ 
tangular boxes around words the command 

.BX word 

will print I word I as shown. The boxes will 
not be neat on a terminal, and this should 

not be used as a substitute for italics. _ 

Longer pieces of text may be boxed by 
enclosing them with .Bl and .B2: 

.Bl 

text... 

.B2 

as has been done here. _ 

Keeping blocks together. If you wish 
to keep a table or other block of lines 
together on a page, there are “keep - 


* Like this. 
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release’' commands. If a block of lines pre- 
ceded by .KS and followed by .KE does not 
fit on the remainder of the current page, it 
will begin on a new page. Lines bracketed 
by .DS and .DE commands are automatically 
kept together this way. There is also a 
“keep floating’* command: if the block to be 
kept together is preceded by .KF instead of 
.KS and does not fit on the current page, it 
will be moved down through the text until 
the top of the next page. Thus, no large 
blank space will be, introduced in the docu¬ 
ment. 

NroffITroff commands. Among the 
useful commands from the basic formatting 
programs are the following. They all work 
with both typesetter and computer terminal 
output: 

.bp - begin new page. 

.br - “break”, stop running text 
from line to line, 
spn - insert n blank lines, 
jxa - don't adjust right margins. 

Date. By default, documents produced 
on computer terminals have the date at the 
bottom of each page; documents produced 
on the typesetter don’t. To force the date, 
say “.DA”. To force no date, say *\ND”. 
To lie about the date, say “.DA July 4, 
1776” which puts the specified date at the 
bottom of each page. The command 

.ND May 8, 1945 

in ’.RP" format places the specified date on 
the cover sheet and nowhere else. Place 
this line before the title. 

Signature line. You can obtain a sig¬ 
nature line by placing the command .SG in 
the document. The authors’ names will be 
output in place of the .SG line. An argu¬ 
ment to .SG is used as a typing identification 
line, and placed after the signatures. The 
.SG. command is ignored in released paper 
format. * 

Registers. Certain of the registers 
used by —ms can be altered to change 
default settings. They should be changed 
with .nr commands, as with 

.nr PS 9 

to make the default point size 9 point. If 
the effect is needed immediately, the normal 


troff command should be used in addition to 
changing the number register. 


Register Defines 

Takes 

effect 

Default 

PS 

point size 

next para. 

10 

vs 

line spacing 

next para. 

12 pts 

LL 

line length 

next para. 

6” 

LT 

title length 

next para. 

6" 

PD 

para, spacing 

next para. 

0.3 VS 

PI 

para, indent 

next para. 

5 ens 

FL 

footnote length 

next FS 

11/12 LL 

cw 

column width 

next 2C 

7/15 LL 

GW 

intercolumn gap. 

next 2C 

1/15 LL 

PO 

page offset 

next page 

26/27" 

HM 

top margin 

next page 

1" 

FM 

bottom margin 

next page 

1" 


You may also alter the strings LH, CH, and 
RH which are the left, center, and right 
headings respectively; and similarly LF, CF, 
and RF which are strings in the page footer. 
The page number on output is taken from 
register PN, to permit changing its output 
style. For more complicated headers and 
footers the macros PT and BT can be 
redefined, as explained earlier. 

Accents. To simplify typing certain 
foreign words, strings representing common 
accent marks are defined. They precede the 
letter over which the mark is to appear. 
Here are the strings: 


Input 

Output 

Input 

Output 

\*'e 

• 

e 

r* 

m 

a 

re 

e 

\*Ce 

V 

e 


a 

\".c 

c 

\**e 

e 




Use. After your document is prepared 
and stored on a file, you can print it on a 
terminal with the command" 

nroff —ms file 

and you can print it on the typesetter with 
the command 

troff—ms file 

(many options are possible). In each case, 
if your document is stored in several files, 
just list all the filenames where we have 
used “file”. If equations or tables are used, 
eqn and/or tbl must be invoked as prepro¬ 
cessors. 


* IT .2C wis used, pipe the nroff output through 

cot; make the first line of the input 44 .pi 
/usr/bin/col." 




References and further study . If you 
have 10 do Greek or mathematics, see egn 
(U for equation setting. To aid eqn users, 
—ms provides definitions of .HQ and .EN 
which normally center the equation and set 
it off slightly. An argument on .HQ is taken 
to be an equation number and placed .in the 
right margin near the equation. In addition, 
there are three special arguments to EQt the* 
letters C, I, and L indicate centered 
(default), indented, and left adjusted equa¬ 
tions, respectively. If there is both a format 
argument and an equation number, give the 
format argument first, as in 

.EQ L (L3a) 

for a left-adjusted equation numbered 
(1.3a). 

Similarly, the macros .TS and .TE are 
defined to separate tables (see (21) from text 
with a little space. A very long table with a 
heading may be broken across pages by 
beginning it with .TS H instead of .TS, and 
placing the line .TH in the table data after 
the heading. If the table has no heading 
repeated from page to page, just use the 
ordinary .TS and .TE macros. 

To learn more about trojf see (31 for a 
general introduction, and (4] for the full 
details (experts only). Information on 
related UNIX commands is in (51. For jobs 
that do not seem well-adapted to —ms, con¬ 
sider other macro packages. It is often far 
easier to write a specific macro packages for 
such tasks as imitating particular journals 
than to try to adapt —ms. 

Acknowiedgment. Many thanks are 
due to Brian Kemighan for his help in the 
design and implementation of this pa ck age, 
and for his assistance in preparing this 
manual. 
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Appendix A 


List of Commends 

# 


1C 

0 

Return to single column format 

LG 

Increase type size. 

2C 

Start double column format 

LP 

Left aligned block paragraph. 

AB 

Begin abstract 



AE 

End abstract 



AI 

Specify author’s institution. 



AU 

Specify author. 

ND 

Change or cancel date. 

B 

Begin boldface. 

NH 

Specify numbered heading. 

DA 

Provide the date on each page. 

NL 

Return to normal type size. 

DE 

End display. 

PP 

Begin paragraph. 

DS 

Start display (also CD, LD, ID). 



EN 

End equation. 

R 

Return to regular font (usually Roman). 

EQ 

Begin equation. 

‘ RE 

End one level of relative indenting. 

FE 

End footnote. 

RP 

Use released paper format 

FS 

Begin footnote. 

RS 

Relative indent increased one level. 



SG 

Insert signature line. 

I 

Begin italics. 

SH 

Specify section heading 



SM 

Change to smaller type size. 

IP 

Begin indented paragraph. 

• TL 

Specify title. 

KE 

Release keep. 



KF 

Begin floating keep. 

UL 

Underline one word. 

KS 

Start keep. 




Register Names 


The following register names are used by —ms internally. Independent use of these 


names 

in one's own macros may produce incorrect output 

Note that no lower case letters are 

used in any — 

ms internal name. 











Number registers used in — 

ms 




• 

DW 

GW 

HM 

IQ 

LL 

NA 

OJ 

PO 

T. 

TV 

#T 

EF 

HI 

HT 

IR 

LT 

NC 

PD 

PQ 

TB 

vs 

IT 

FL 

H3 

IK 

K1 

MM 

NF 

PF 

PX 

TD 

YE 

AV 

FM 

H4 

IM 

LI 

MN 

NS 

PI 

RO 

TN 

YY 

cw 

FP 

• H5 

IP 

LE 

MO 

01 

PN 

ST 

TQ 

ZN 





String registers used in —ms 




• 

AS 

CB 

DW 

EZ 

I 

KF 

MR 

R1 

RT 

TL 

% 

AB 

CC 

DY 

FA 

11 

KQ 

ND 

R2 

SO 

TM 

* 

AE 

CD 

El 

FE 

12 

KS 

NH 

R3 

SI 

TQ 


AI 

CF 

E2 

FJ 

13 

LB 

NL 

R4 

S2 

TS 

* 

AU 

CH 

E3 

FK 

14 

LD 

NP 

R5 

SG 

TT 

« 

B 

CM 

E4 

FN 

15 

LG 

OD 

RC 

SH 

UL 

1C 

BG 

CS 

E5 

FO 

ID 

LP 

OK 

RE 

SM 

WB 

2C 

BT 

CT 

EE 

FQ 

IE 

ME 

PP 

RF 

SN 

WH 

Al 

C 

D 

EL 

FS 

IM 

MF 

PT 

RH 

SY 

WT 

A2 

Cl 

DA 

EM 

FV 

IP 

MH 

PY 

RP 

TA 

XD 

A3 

C2 

DE 

EN 

FY 

IZ 

MN 

QF 

RQ 

TE 

XF 

A4 

CA 

DS 

EQ 

HO 

KE 

MO 

R 

RS 

TH 

XK 


Order of Commands in Input 




I 


Figure 1 
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A Guide to Preparing 
Documents with —ms 


M. £ Lesk 

Bel! Laboratories August 1978 


This guide gives some simple examples of do¬ 
cument preparation on Bell Labs computers, 
emphasizing the use of the —ms macro pack¬ 
age. It enormously abbreviates information in 

1. Typing Documents on UNIX and GCOS, by 
M. E. Lesk; 

2. Typesetting Mathematics — User's Guide, 
by B. W. Kemighan and L. L. Cherry; and 

3. Tbl — A Program to Format Tobies, by M. 
E. Lesk. 

These memos are all included in the UNIX 
Programmer's Manual, Volume 2. The new 
user should also have A Tutorial Introduction to 
the UNIX Text Editor, by B. W. Kemighan. 

For more detailed information, read Advanced 
Editing on UNIX snd A Troff Tutorial, by B. W. 
Kemighan, and (for experts) NroJJTTroff Refer¬ 
ence Manual by J. F. Ossanna. Information on 
related commands is'found (for UNIX users) in 
UNIX for Beginners by B. W. Kemighan and 
the UNIX Programmer's Manual by K. Thomp¬ 
son and D. M. Ritchie. 


Contents 

ATM.2 

A released paper.3 

An internal memo, and headings ... 4 

Lists, displays, and footnotes .5 

Indents, keeps, and double column . 6 

Equations and registers.7 

Tables and usage.8 


Throughout the examples, input is shown in 
this Helvetica sans serif font 
while the resulting output is shown in 
this Times Roman font 


UNIX Document no. 1111 


Commands for a TM 

.TM 1978-503 99999 99999-11 

.NO April 1. 1976 

.TL 

The Role of the Allen Wrench in Modern 
Electronics 

All *MH 2G-111* 2345 

J. Q. Pencilpusher 

AU *MH IK-222* 5432 

X. Y. Hardwired 

Al 

,MH 

.OK 

Tools 

Design 

AB 

This abstract should be.short enough to 
fit on s single page cover sheet 
It must attract the reader into sending for 
the complete memorandum. 

AE 

.CS 10 2 12 5 6 T 
.NH 

Introduction. 

.PP 

Now the first paragraph of actual text _ 

Last line of text 

.SG MH-1234-JQP/XYH-unix 

.NH 

References _ 

Commands not needed in a particular format are ig¬ 
nored. 


@ MUtwwia Cover Sheet for TM 


Thts mformmtto m * for emohmn of Of* L t O o ro mnn . (GEI /J. 


Title* The Rota of the Alien Wrench Dai*- April 1, 1976 

in Modern Electronics 

TM. I971-5b3 

Other lterm*. Tools 
Design 


Author Location Exl Charting Caar- 99999 

J. Q. Pendlpusher MH 2G-111 2345 Filing Caao- 99999s 
X. Y. Hardwired MH iK-222 5432 


ABSTRACT 

This abstract should be short enough to 
At on a single page cover sheet. It must 
attract the reader into sending for the com- 
plete memorandum. 



Pages Text 1C 

No. Figures 5 

Other 2 

No. Tables 6 

Total 12 

No. Refs. 7 


E-I932-U (4-73) 

SEE REVERSE SIDE FOR DISTRIBUTION UST 


_ i 
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A Released Paper with Mathematics 


An Internal Memorandum 


£Q 

deiitn SS 

,£N 

.FP 

„ (*i for t TM) 

.CS 10212567 
.NH 

Introduction 

.PP 

The solution to the torque handle aquation 
-£Q (1) 

sum from 0 to inf F ( x sub I) • G ( x) 

.£N 

is found with tha transformation S x — rho ovar 
theta S whara S rho — G prime (x) S and SthataS 
la derived - 


Tha Role of tha Allan Wrench 
in Modern El ec tr o ni c s 

L Q. * * a< p~*r 

x. r. fau w 

Beil Laboratories 
Murray Hifl. New Jersey 07974 

ABSTRACT 

This abstract should be short enough to At on a 
angle pegs cover s heet . It must attract the 
reader into sending for the complete memoran¬ 
dum. 


April l, 1976 


The Role of the Allan Wrench 
in Modern Electronics 

J. Q. Pmalptahtr 

X Y. Han Wtf 

Beil Laboratories 
Murray HilL New Jersey 07974 


1. Introduction 

The solution to the torque handle equation 

£f(x,)-<7<jr) (1) 

0 

is found with (he transformation .rwhere p-<7'(jr) and 
9 is derived from well-known principles. 


.IM 

.NO January 24, 1956 
.TL 

Tha 1956 Consent Oacraa 

Able, Bakar & 

Chari ay, A tty a. 

PP 

Plaintiff, Unitad Stataa of America. having filed 
its complaint harain on January 14, 1949; tha 
dafandants having appaarad and filed thair 
an awar to such comolaint danying tha 
subatantiva ailagations tharaof: and tha parties, 
by thair attorneys, - 



Subjacc Tha 1956 Constat Decree due Jen aery 24, 1956 

from: Able, Bakar 4 
Charley, Anya. 


Plaintiff, United States of America, having filed its com* 
plaint herein on January 14, 1949: the defendants havmf 
appeared and filed their answer to such complaint denymt 
the substantive allegations thereof: and the parties, by their 
attorneys, having severally consented to the entry of this 
Final Judgment, without trial or adjudication of any issues 
of fact or law herein and without this Final Judgment con* 
shotting any evidence or admission by any party in respect 
of any such issues: 

Now, therefore before any testimony has been taken 
herein, and without trial or adjudication of any issue of fact 
or law herein, and upon the consent of ail parties hereto, it 
is hereby 

Ordered, adjudged and decreed as follows: 

L [Sherman Acti 

This Court has jurisdiction of (he subject matter herein 
and of ail the panics hereto. The complaint states a claim 
upon which relief may be grimed against each of the 
defendants under Sections 1, 2 and 3 of the Act of 
Congress of July 2, 1890, entitled “An act to protect trade 
and commerce against unlawful restraints and monopo¬ 
lies,’* commonly known as the Sherman Act, as amended. 

IL [DeAnitioasi 

For the purposes of this Final Judgmenc 

(a) “Western “ shall mean the defendant Western Elec¬ 
tric Company, Incorporated. 


Other formats possible (specify before .TL) are: .MR 
(“memo for record**), .MF (“memo for file**), .EG 
(“engineer’s notes’*) and .TR (Computing Science 
Tech. Report). 


Headings 


.NH 

Introduction. 

.PP 

text text text 

1. Introduction 
text text text 


SH 

Aocendix l 
po 

text text text 

Appendix I 
text text text 
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A Simple List 

jp 

i. Pqncilpushtr and X. Hardwired, 

J 

A Haw Kind of Sat Screw. 

3 

Proc. IEEE 
3 75 

(1978). 23*255. 

JP 2. 

H. Nails and R. Irons, 

J 

Pastanare (or Printed Circuit Boards. 
Jt 

Proc. ASME 
B 23 

(1974), 23-24. 

XP (terminates list) 


Multiple Indents 

This is ordinary text to point out 
tha margins of the page. 

.IP 1. 

First level item 
.RS 

.IP a) 

Second level, 

.IP b) 

Continued here with another second 
level Item, but somewhat longer. 

.RE 
.IP 2. 

Return to previous value of the 
Indenting st this point 
.IP 3. 

Another 

line. 


1. J. Penciipusher and X. Hardwired, A Nr* Kind 
of Set Sere ». Proc IEEE 75 (1976), 23*255. 

1 H. Nails and R. Irons, Fasteners for Primed Or- 
ctut Boards. Proc. ASME 23 (1974), 23*24. 


Dispitys 

text text text text text text 

ns 

and now 
for something 
completely different 
JOE 

text text text text text text 

hoboken Harrison newark rose villa avenue grove 
street east orange brick church orange highland ave¬ 
nue mountain station south orange mapiewood 
milibum short hills summit new providence 

and now 

for something 

completely different 

murrey hill berkeiey heights gillette Stirling milling- 
ton tyons basking ridge bemardsville far hills 
peapadt gladstone 

Options: OS L left-adjust; .OS C: line-by-line 
center. .DS B: make block, then center. 


Footnotes 


This is ordinary text to point out the margins of the 
page. 

1. First level item 

a) Second level. 

b) Continued here with another second level 
item, but somewhat longer. 

2. Return to previous value of the indenting at this 
point. 

3. Another line. 


Keeps 

Lines bracketed by the following commands are kept 
together, and will appear entirely on one page: 

.KS not moved -KF may float 

.KE through text XE in text 


Double Column 

.TL 

Tha Declaration of Independence 

.2C 

.PP 

When-in the course of human events, it becomes 
necessary for one people to dissolve the 
political bonds which have connected them with 
another, and to assume among the powers of the 
earth the separate and equal station to which 
the laws of Nature and of Nature's God entitle 
them, a decent respect to the opinions of 


Among the most important occupants 
of the workbench are the long-nosed pliers. 
Without these basic tools* 

FS 

* As first shown by Tiger & Leopard 
(1975). 

.FE 

few assemblies could be completed. They may 
lack the popular appeal of the sledgehammer 


Among the most important occupants of the work¬ 
bench are the long-nosed pliers. Without these basic 
tools* few assemblies could be completed. They 
may lack the popular appeal of the sledgehammer 


* As first shown by Titer A Leopard (1975). 


The Declaration of Independence 


When in the course of 
human events, it be¬ 
comes necessary for one 
people to dissolve the 
political bonds which 
have connected them 
with another, and to as¬ 
sume among the powers 
of the earth the separate 
and equal station to 
which the laws of Nature 
and of Nature's God en¬ 
title them, a decent 
respect to the opinions 
of mankind requires that 


they should declare the 
causes which impel them 
to the separation. 

We hold these truths 
to be self-evident, that 
all men are created 
equal, that they are en¬ 
dowed by their creator 
with certain unalienable 
rights, that among these 
are life, liberty, and the 
pursuit of happiness. 
That to secure these 
rights, governments are 
instituted among men. 
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Equations 

A disoiayed equation is marked 

with an eouation number at th * " iar9 

by adding an argument to the EQ l' 0 *- 

•«>*•*• *«« to 1 suo * + ' u ' t ‘' 1 
.EN 

A displayed equation is marked with an elution 
number at the right margin by adding an argument 
to the EQ tine: _ 

iL . sfp?+iiz+r 
a 1 


“a Vwr’iub nu--1.lt t OH. l.*r*Vr* 
c 1 right ] + left l matrix ( cot l A<11) above • - 

above . I cot l. above. above .1 col {. above . 
above A<33) II right ] cdot left ( bile l a*®*® 
above beta above gamma I ngnt j 
EN 


V.- 



Vd (11) 


A (33) 1 


(2.2a) 


i del V | sup 2 


EQ L 

F hat ( chi) " mark 
.EN 

lineup -* Heft ( {partial V) over 1®**]** l *]i f !2Jt 
1 sup 2 «► l left ({partial V| over {partial yl right 

) | sup 2-lambda *> inf 

.EN 

* X ).|VK|* 

-lef-ls" 

S a dot S. S b dotdotS, S xi tilde times y vecS: 

■ a £ | X y. (with deiim $S on, see panel 3). 

See also the equations in the second table, panel 8. 


Some Registers You Can Change 


Line length 
.nr LL 71 

Title length 
.nr LT 7i 

Point size 
.nr PS 9 

Vertical spacing 
.nr VS 11 

Column width 
.nr CW 3i 


Paragraph spacing 
.nr PD 0 

Page offset 
.nr PO 0.5i 

Page heading 

.ds CH Appendix 
(center) 

.ds RH 7-25-76 
(right) 

.ds LH Private 
(left) 


Intercolumn spacing Page footer 

.nr GW ,5i .ds CF Draft 

Margins - head and foot •‘J* similar 
.nr HM .755 ds RF 

.nr FM .75i Page numbers 

Paragraph indent ‘ nr ^ ^ 

.nr PI 2n 


Tables 


.TS (® indicates a lab) 


allbox: 
css 
c c c 
n n n. 

AT&T Common Stock 
Year O Price ® Oividend 
1P71 ®41-54.®S2.60 
2®41-54®2.70 
3 ® 46-55 ® 2.37 

4® 40-53® 3.24 
5® 45-52® 3.40 
6® 51-59®.95* 

.TE 

• (first quarter only) 

The meanings of the key-letters describing the align- 


AT&T Common Stocx 

Year] 

Price 

Dividend 

1971 

4J-541 

S2.60 

2 

41-541 

2.70 

3 

46-55 

2.87 

”Z1 

40-53 

3.24 

5 

45-52 

3.40 

6 

51-59 

.95* 


* (first quarter only) 


ment of each entry are: 

C center n numerical 

r right-adjust a subcolumn 

I left-adjust a spanned 

The global table options are center, expand, box. 

* * . ..._w /-l i;#4**tf <S (it I 


.TS (with deiim SS on. see panel 3) 

doublebox. center 
ec 
11. 

Name® Definition 


Gamma ® SGAMMA (z) - int sub 0 sup inf \ 
t sup {z-11 e sup -t dtS ; 

Sine®Sain U) - 1 over 21 ( e sup tx - e sup -«x )S 
Error ®S roman erf (z) - 2 over sqrt pi \ 
int sub 0 sup z e sup (-t sup 21 dt5 
8essel®S J sup 0 (z) - 1 over P' \ 
int sub 0 sup oi cos ( z sin theta ) d theta S 

Zeta®S zata (a) - \ . . 1)s 

sum from k-1 to mf k sup-a (Res>U5 
TS 


Name 

Definition 



Gamma 

r<-)“Jo r-'fdt 

Sine 

sin (.t)—■— (*“ *“*) 

Error 


Bessel 

y (-).-L f cos(zsin0)</0 
i r J0 

Zeta 

«(*)-£*- (Rei>l> 




Usage 


Documents with just text: 
troff -ms files 

With equations only: 
eqn files | troff -ms 
With tables only: 
tbi files | troff -ms 

With both tables and equations: 

tbl files! eqn I troff -ms _ 

The above generates STARE output on GCOS: replace 
-st with -ph for typesetter output. 
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The UNIX Time-Sharing System* 

D. M. Ritchie and K. Thompson' 


ABSTRACT 

UNDCf is a general-purpose, multi-user, interactive operating system for 
the larger Digital Equipment Corporation PDP-11 and the Interdata 8/32 com¬ 
puters. It offers a number of features seldom found even in larger operating 
systems, including 

i A hierarchical hie system incorporating demountable volumes, 

ii Compatible file, device, and inter-process I/O, 

iii The ability to initiate asynchronous processes, 

iv System command language selectable on a per-user basis, 

v Over 100 subsystems including a dozen languages, 

vi High degree of portability. 

This paper discusses the nature and implementation of the file system and of 
the user command interface. 

1. INTRODUCTION 

There have been four versions of the UNIX time-sharing system. The earliest (circa 
1969-70) ran on the Digital Equipment Corporation PDP-7 and -9 computers. The second ver¬ 
sion ran on the unprotected PDP-11/20 computer. The third incorporated multiprogramming 
and ran on the PDP-11/34, /40, /45,760, and /70 computers; it is the one described in the pre¬ 
viously published version of this paper, and is also the most widely used today. This paper 
describes only the fourth, current system that runs on the PDP-11/70 and the Interdata 8/32 
computers. In fact, the differences among the various systems is rather small; most of the revi¬ 
sions made to the originally published version of this paper, aside from those concerned with 
style, had to do with details of the implementation of the file system. 

Since PDP-11 UNIX became operational in February, 1971, over 600 installations have been 
put into service. Most of them are engaged in. applications such as computer science education, 
the preparation and formatting of documents and other textual material, the collection and pro¬ 
cessing of trouble data from various switching machines within the Beil System, and recording 
and checking telephone service orders. Our own installation is used mainly for research in 
operating systems, languages, computer networks, and other topics in computer science, and 
also for document preparation. 

Perhaps the most important achievement of UNIX is to demonstrate that a powerful 
operating system for interactive use need not be expensive either in equipment or in human 
effort: it can run on hardware costing as little as 540,000, and less than two man-years were 
spent on the main system software. We hope, however, that users find that the most important 

* Copyright 1974, Association for Computing Machinery, Inc, reprinted by permission. This is a revised ver¬ 
sion of an article that appeared in Communications of the acm, /7, No. 7 (July 1974), pp. 365*375. That arti¬ 
cle was a revised version of a paper presented at the Fourth acm Symposium on Operating Systems Princi¬ 
ples, ism Thomas J. Watson Research Center, York town Heights, New York, October 15-17, 1973. 
tUNIX is a Trademark of Beil Laboratories. 




characteristics of the system are its simplicity, elegance, and ease of use. 

Besides the operating system proper, some major programs available under UNIX are 

C compiler 

Text editor based on QED 1 

Assembler, linking loader, symbolic debugger 

Phototypesetting and equation setting programs 2 ’ 3 

Dozens of languages including Fortran 77, Basic, Snoboi, aPL, Algol 68, Mo, 

TMG, Pascal 

There is a host of maintenance, utility, recreation and novelty programs, all written locally. 
The UNIX user community, which numbers in the thousands, has contributed many more pro* 
grams and languages. It is worth noting that the system is totally self-supporting. All UNIX 
software is maintained on the system; likewise, this paper and all other documents in this issue 
were generated and formatted by the UNIX editor and text formatting programs. 

II. HARDWARE AND SOFTWARE ENVIRONMENT 

The pop-1 1/70 on which the Research UNIX system is installed is a 16-bit word (8-bit 
byte) computer with 768K bytes of core memory*, the system kernel occupies 90K bytes about 
equally divided between code and data tables. This system, however, includes a very large 
number of device drivers and enjoys a generous allotment of space for I/O buffers and system 
tables; a minimal system capable of running the software mentioned above can require as little 
as 96 K. bytes of core altogether. There are even larger installations; see the description of the 
pwb/unix systems,' 1 - 3 for example. There are also much smaller, though somewhat restricted, 
versions of the system. 6 

Our own pop- 11 has two 200-Mb moving-head disks for file system storage and swapping. 
There' are 20 variable-speed communications interfaces attached to 300- and 1200-baud data 
sets, and an additional 12 communication lines hard-wired to 9600-baud terminals and satellite 
computers. There are also several 2400- and 4800-baud synchronous communication interfaces 
used for machine-to-machine file transfer. Finally, there is a variety of miscellaneous devices 
including nine-track magnetic tape, a line printer, a voice synthesizer, a phototypesetter, a digi¬ 
tal switching network, and a chess machine. 

The preponderance of UNIX software is written in the abovementioned C language. 7 Early 
versions of the operating system were written in assembly language, but during the summer of 
1973, it was rewritten in C. The size of the new system was about one-third greater than that 
of the old. Since the new system not only became much easier to understand and to modify 
but also Included many functional improvements, including multiprogramming and the ability 
to share reentrant code among several user programs, we consider this increase in size quite 
acceptable. 

in. THE FILE SYSTEM 

The most important role of the system is to provide a file system. From the point of view 
of the user, there are three kinds of files: ordinary disk files, directories, and special files. 

3.1 Ordinary fil« 

A file contains whatever information the user places on it. for example, symbolic or 
binary (object) programs. No particular structuring is expected by the system. A file of text 
consists simply of a string of characters, with lines demarcated by the newline character. Binary 
programs are sequences of words as they will appear in core memory when the program starts 
executing. A few user programs manipulate files with more structure; for example, the assem¬ 
bler generates, and the loader expects, an object file in a particular format. However, the struc¬ 
ture of files is controlled by the programs that use them, not by the system. 
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3.2 Directories 

Directories provide the mapping between the names of hies and the hies themseives, and 
thus induce a structure on the hie system as a whole. Each user has a directory of his own 
hies: he may also create subdirectories to contain groups of hies conveniently treated together. 
A directory behaves exactly like an ordinary hie except that it cannot be written on by 
unprivileged programs, so that the system controls the contents of directories. However, any¬ 
one with appropriate permission may read a directory just like any other hie. 

The system maintains several directories for its own use. One of these is the root direc¬ 
tory. All hies in the system can be found by tracing a path through a chain of directories until 
the desired hie is reached. The starting point for such searches-is often the root. Other system 
directories contain all the programs provided for general use; that is, all the command! As will 
be seen, however, it is by no means necessary that a program reside in one of these directories 
for it to be executed. 

Files are named by sequences of 14 or fewer characters. When the name of a hie is 
specified to the system, it may be in the form of a path name, which is a sequence of directory 
names separated by slashes, “/”, and ending in a hie name. If the sequence begins with a 
slash, the search begins in the root directory. The name /alpha/beta/gamma causes the sys¬ 
tem to search the root for directory alpha, then to search alpha for beta, finally to hnd g«mm« 
in beta, gamma may be an ordinary hie, a directory, or a special hie. As a limiting case, the 
name *7” refers to the root itself. 

A path name not starting with *7" causes the system to begin the search in the user’s 
current directory. Thus, the name alpha/beta specifies the hie named beta in subdirectory 
alpha of the current directory. The simplest kind of name, for example, alpha, refers to a file 
that itself is found in the current directory. As another limiting case, the null file name refers 
to the current directory. 

The same non-directory file may appear in several directories under possibly different 
names. This feature is called linking; a directory entry for a hie is sometimes called a link. The 
UNIX system differs from other systems in which linking is permitted in that all links to a file 
have equal status. That is, a file does not exist within a particular directory, the directory entry 
for a file consists merely of its name and a pointer to the information actually describing the 
hie. Thus a hie exists independently of any directory entry, although in practice a file is made 
to disappear along with the last link to it 

Each directory always has at least two entries. The name “. ” in each directory refers to 
the directory itself. Thus a program may read the current directory under the name 
without knowing its complete path name. The .tame by convention refers to the parent 
of the directory in which it appears, that is, to the directory in which it was created. 

The directory structure is constrained to have the form of a rooted see. Except for the 
special entries “ . ” and “..", each directory must appear as an entry in exactly one other 
directory, which is its parent. The reason for this is to simplify the writing of programs that 
visit subtrees of the directory structure, and more important, to avoid the separation of portions 
of the hierarchy. If arbitrary links to directories were permitted, it would be quite difficult to 
detect when the last connection from the root to a directory was severed. 

3-3 Special files 

Special hies constitute the most unusual feature of the UNIX file system. Each supported 
I/O device is associated with at least one such file. Special files are read and written just like 
ordinary disk files, but requests to read or write result in activation of the associated device. 
An entry for each special file resides in directory /dev, although a link may be made to one of 
these files just as it may to an ordinary file. Thus, for example, to write on a magnetic tape one 
may write on the file /dev/mt Special files exist for each communication line, each disk, each 
tape drive, and for physical main memory. Of course, the active disks and the memory special 
file are protected from indiscriminate access. 
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There is a threefold advantage in treating I/O devices this way*. Ate and device I/O are as 
similar as possible; ole and device names have the same syntax and meaning, so that a program 
expecting a file name as a parameter can be passed a device name; finally, special files are sub* 
ject to the same protection mechanism as regular files. 

3.4 Removable file systems 

Although the root of the file system is always stored on the same device, it is not neces¬ 
sary that the entire file system hierarchy reside on this device. There is a mount system 
request with two arguments: the name of an existing ordinary file, and the name of a special file 
whose associated storage volume (e.g., a disk pack) should have the structure of an indepen¬ 
dent file system containing its own directory hierarchy. The effect of mount is to cause refer¬ 
ences to the heretofore ordinary file to refer instead to the root directory of the file system on 
the removable volume. In effect, mount replaces a leaf of the hierarchy tree (the ordinary file) 
by a whole new subtree (the hierarchy stored on the removable volume). After the mount, 
there is virtually no distinction between files on the removable volume and those in the per¬ 
manent file system. In our installation, for example, the root directory resides on a small parti¬ 
tion of one of our disk drives, while the other drive, which contains the user’s files, is mounted 
by the system initialization sequence. A mountable file system is generated by writing on its 
corresponding special file. A utility program is available to create an empty file system, or one 
may simply copy an existing file system. 

There is only one exception to the rule of identical treatment of files on different devices: 
no link may exist between one file system hierarchy and another. This restriction is enforced 
so as to avoid the elaborate bookkeeping that would otherwise be required to assure removal of 
the links whenever the removable volume is dismounted. 

3J5 Protection 

Although the access consol scheme is quite simple, it has some unusual features. Each 
user of the system is assigned a unique user identification number. When a file is created, it is 
marked with the user ID of its owner. Also given for new files is a set of ten protection bits. 
Nine of these specify independently read, write, and execute permission for the owner of the 
file, for other members of his group, and for all remaining users. 

If the tenth bit is on. the system will temporarily change the user identification (hereafter, 
user ID) of the current user to that of the creator of the file whenever the file is executed as a 
p rogr a m. This change in user ID is effective only during the execution of the program that calls 
for it. The set-user-iD feature provides for privileged programs that may use files inaccessible 
to other users. For example, a program may keep an accounting file that should neither be read 
nor changed except by the program itself. If the set-user-iD bit is on for the program, it may 
access the file although this access might be forbidden to other programs invoked by the given 
program's user. Since the actual user ID of the invoker of any program is always available, set- 
user-ID progr ams may take any measures desired to satisfy themselves as to their invoker’s 
credentials. This mechanism is used to allow users to execute the carefully written commands 
that call privileged system entries. For example, there is a system entry invokable only by the 
“ 4 super-user” (below) that creates an empty directory. As indicated above, directories are 
expected to have entries for “. ” and “.. ”. The command which creates a directory is owned 
by the super-user and has the set-user-ID bit set. After it checks its invoker’s authorization to 
create the specified directory, it creates it and makes the entries for “. ” and 44 .. ”. 

Because anyone may set the set-user- ID bit on one of his own files, this mechanism is 
generally- available without administrative intervention. For- example, this protection scheme 
easily solves the moo accounting problem posed by “Aleph-null.” 3 

The system recognizes one particular user ID (that of the “super-user”) as exempt from 
the usual constraints on file access; thus (for example), programs may be written to dump and 
reload the file system without unwanted interference from the protection system. 
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3.6 1/0 calls 

The system calls to do I/O are designed to eliminate the differences between the various 
devices and styles of access. There is no distinction between “random*’ and “sequential** 1/0. 
nor is any logical record size imposed by the system. The size of an ordinary file is determined 
by the number of bytes written on it; no predetermination of the size of a file is necessary or 
possible. 

To illustrate the essentials of I/O, some of the basic calls are summarized below in an 
anonymous language that will indicate the required parameters without getting into the underly¬ 
ing complexities. Each call to the system may potentially result in an error return, which for 
simplicity is not represented in the calling sequence. 

To read or write a file assumed to exist already, it must be opened by the following call: 
filep ■■ open (name, flag) 

where name indicates the name of the file. An arbitrary path name may be given. The flag 
argument indicates whether the file is to be read, written, or “updated,” that is, read and writ¬ 
ten simultaneously. 

The returned value filep is called a file descriptor. It is a small integer used to identify the 
file in subsequent calls to read, write, or otherwise manipulate the file. 

To create a new file or completely rewrite an old one, there is a create system call that 
creates the given file if it does not exist, or truncates it to zero length if it does exist; create 
' also opens the new file for writing and, like open, returns a file descriptor. 

The file system maintains no locks visible to the user, nor is there any restriction on the 
number of users who may have a file open for reading or writing. Although it is possible for 
the contents of a file to become scrambled when two users write on it simultaneously, in prac¬ 
tice difficulties do not arise. We take the view that locks are neither necessary nor sufficient, in 
our environment, to prevent interference between users of the same file. They are unnecessary 
because we are not faced with large, single-file data bases maintained by independent processes. 
They are insufficient because locks in the ordinary sense, whereby one user is prevented from 
writing on a file that another user is reading, cannot prevent confusion when, for example, both 
users are editing a file with an editor that makes a copy of the file being edited. 

There are, however, sufficient internal interlocks to maintain the logical consistency of the 
file system when two users engage simultaneously in activities such as writing on the same file, 
creating files in the same directory, or deleting each other’s open files. 

Except as indicated below, reading and writing are sequential. This means that if a partic¬ 
ular byte in the file was the last byte written (or read), the next I/O call implicitly refers to the 
immediately following byte. For each open file there is a pointer, maintained inside the system, 
that indicates the next byte to be read or written. If n bytes are read or written, the pointer 
advances by n bytes. 

Once a file is open, the following calls may be used: 

n ” read (filep, buffer, count) 
n — write (filep, buffer, count) 

Up to count bytes are transmitted between the file specified by filep and the byte array specified 
by buffer. The returned value n is the number of bytes actually transmitted. In the write case, 
n is the same as count except under exceptional conditions, such as I/O errors or end of physi¬ 
cal medium on special files; in a read, however, n may without error be less than count If the 
read pointer is so near the end of the file that reading count characters would cause reading 
beyond the end. only sufficient bytes are transmitted to reach the end of the file; also, 
typewriter-like terminals never return more than one line of input. When a read call returns 
with n equal to zero, the end of the file has been reached. For disk files this occurs when the 
read pointer becomes equal to the current size of the file. It is possible to generate an end-of- 
file from a terminal by use of an escape sequence that depends on the device used. 







Bytes written affect only those pans of a file implied by the position of the write pointer 
and the count; no other pan of the file is changed. If the last byte lies beyond the end of the 
file, the file is made to grow as needed. 

To do random (direct-access) I/O it is only necessary to move the read or write pointer to 
the appropriate location in the file. 

location » Iseek (filep, offset, base) 

The pointer associated with filep is moved to a position offset bytes from the beginning of the 
file, from the current position of the pointer, or from the end of the file, depending on base, 
offset may be negative. For some devices (e.g., paper tape and terminals) seek calls are 
ignored. The actual offset from the beginning of the file to which the pointer was moved is 
returned in location. 

There are several additional system entries having to do with I/O and with the file system 
fh iat will not be discussed. For example: close a file, get the status of a file, change the protec¬ 
tion mode or the owner of a file, create a directory, make a link to an existing file, delete a file. 

IV. IMPLEMENTATION or THE FILE SYSTEM 

As mentioned in Section 3.2 above, a directory entry contains only a name for the assod* 
ated file and a pointer to the file itself. This pointer is an integer called the dumber (for index 
number) of the file. When the file is accesse d , it? i-oumber is used as an index into a system 
table (the i-iist) stored in a known pan of the device on which the directory resides. The entry 
found thereby (the file’s ) contains the description of the file: 

i the user and group-tD of its owner 

ii its protection bits 

iii the physical disk or tape addresses for the file contents 

iv its size 

v time of creation, last use, and last modification 

vi the number of links to the file, that is, the number of times it appears in a directory 

vii a code indicating whether the file is a directory, an ordinary file, or a special file. 

The purpose of an open or create system call is to turn the path name given by the user into an 
i-aumber by searching the explicitly or implicitly named directories. Once a file is open, its 
device, i-oumber, and read/write pointer are stored in a system table indexed by the file 
descriptor returned by the open or create. Thus, during a subsequent call to read or write the 
file, the descriptor may be easily related to the information necessary to access the file. 

When a new file is created, an i-aode is allocated for it and a directory entry is made that 
contains the name of the file and the i-node number. Making a link to an existing file involves 
creating a directory entry with the new name, copying the i*number from the original file entry, 
and incrementing the link-count field of the i-node. Removing (deleting) a file is done by 
decrementing the link-count of the i-aode specified by its directory entry and erasing the direc¬ 
tory entry. If the link-count drops to 0, any disk blocks in the file are freed and the i-aode is 
de-ailocated. 

The space on all disks that contain a file system is divided into a number of 512-byte 
blocks logically addressed from 0 up to a limit that depends on the device. There is space in 
the i-aode of each file for 13 device addresses. For nonspecial files, the first 10 device 
addresses point at the first 10 blocks of the file. If the file is larger than 10 blocks, the 11 dev¬ 
ice address points to an indirect block containing up to 128 addresses of additional blocks in the 
ale. Still larger files use the. twelfth device address of the i-node to point to a double-indirect 
block naming 128 indirect blocks, each pointing to 128 blocks of the file. If required, the thir¬ 
teenth device address is a triple-indirect block. Thus files- may conceptually grow to 
((10+ 128 + 123 : +128^-512) bytes. Once opened, bytes numbered below 5120 can be read 
with a single disk access; bytes in the range 5120 to 70,656 require two accesses; bytes in the 






range 70,656 to 8,459,264 require three accesses; bytes from there to the largest file 
(1,082,201,088) require four accesses. In practice, a device cache mechanism (see below) 
proves effective in eliminating most of the indirect fetches. 

The foregoing discussion applies to ordinary files. When an I/O request is made to a file 
whose i-node indicates that it is special, the last 12 device address words are immaterial, and 
the first specifies an internal device name, which is interpreted as a pair of numbers represent¬ 
ing, respectively, a device type and subdevice number. The device type indicates which system 
routine will deal with I/O on that device; the subdevice number selects, for example, a disk 
drive attached to a particular controller or one of several similar terminal interfaces. 

In this environment, the implementation of the mount system call (Section 3.4) is quite 
straightforward, mount maintains a system table whose argument is the i-number and device 
name of the ordinary file specified during the mount, and whose corresponding value is the 
device name of the indicated special file. This table is searched for each i-number/device pair 
that turns up while a path name is being scanned during an open or create; if a match is found, 
the i-number is replaced by the i-number of the root directory and the device name is replaced 
by the table value. 

To the user, both reading and writing of files appear to be synchronous and unbuffered. 
That is, immediately after return from a read call the data are available; conversely, after a 
write the user’s workspace may be reused. In fact, the system maintains a rather complicated 
buffering mechanism that reduces greatly the number of I/O operations required to access a 
file. Suppose a write call is made specifying transmission of a single byte. The system will 
search its buffers to see whether the affected disk block currently resides in main memory; if 
not, it will be read in from the device. Then the affected byte is replaced in the buffer and an 
entry is made in a list of blocks to be written. The return from the write call may then take 
place, although the actual I/O may not be completed until a later time. Conversely, if a single 
byte is read, the system determines whether the secondary storage block in which the byte is 
located is already in one of the system’s buffers; if so, the byte can be returned immediately. If 
not, the block is read into a buffer and the byte picked out 

The system recognizes when a program has made accesses to sequential blocks of a file, 
and asynchronously pre-reads the next block. This significantly reduces the running time of 
most programs while adding little to system overhead. 

A program that reads or writes files in units of 512 bytes has an advantage over a program 
that reads or writes a single byte at a time, but the gain is not immense; it comes mainly from 
the avoidance of system overhead. If a p ro gram is used rarely or does no great volume of I/O, 
it may quite reasonably read and write in units as small as it wishes. 

The notion of the i-list is an unusual feature of UNIX. In practice, this method of organiz¬ 
ing the file system has proved quite reliable and easy to deal with. To the system itself, one of 
its strengths is the fact that each file has a short, unambiguous name related in a simple way to 
the protection, addressing, and other information needed to access the file. It also permits a 
quite simple and rapid algorithm for checking the consistency of a file system, for example, 
verification that the portions of each device containing useful information and those free to be 
allocated are disjoint and together exhaust the space on the device. This algorithm is indepen¬ 
dent of the directory hierarchy, because it need only scan the linearly organized i-list. At the 
same time the notion of the i-list induces certain peculiarities not found in other file system 
organizations. For example, there is the question of who is to be charged for the space a file 
occupies, because all directory entries for a file have equal status. Charging the owner of a file 
is unfair in general, for one user may create a file, another may link to it. and the first user may 
delete the file. The first user is still the owner of the file, but it should be charged to the 
second user. The simplest reasonably fair algorithm seems to be to spread the charges equally 
among users who have links to a file. Many installations avoid the issue by not charging any 
fees at all. 





V. PROCESSES AND IMAGES 

An i mag e is i computer execution environment. It includes a memory image, general 
r^er values, sutus of open files, current directory and the like. An image is the current 
state of a pseudo-computer. 

A process is the execution of an image. While the processor is executing on behalf of a 
process, the i r na g e must reside in main memory; during the execution of other processes it 
remains in main memory unless the appearance of an active, higher-priority process forces it to 
be swapped out to the disk. 

The user-memory part of an image is divided into three logical segments. The program 
text segment begins at location 0 in the virtual address space. During execution, this segment 
is write-protected and a single copy of it is shared among all processes executing the same pro¬ 
gram. At the first hardware protection byte boundary above the program text segment in the 
virtual address space begins a non-shared. writable data segment, the size of which may be 
extended by a system call. Starting at the highest address in the virtual address space is a stack 
segment, which automatically grows downward as the stack pointer fluctuates. 

5.1 Processes 

Except while the system is bootstrapping itself into operation, a new process can come 
into existence only by use of the fork, system call: 

processed • fork () 

When fork is executed, the process splits into two independently executing processes. The two 
processes have independent copies of the original .memory image, and share all open files. The 
new processes differ only in that one is considered the parent process: in the parent, the 
returned processid actually identifies the child process and is never 0, while in the child, the 
returned value is always 0. 

t he values returned by fork in the parent and child process are distinguishable, 
each process may determine whether it is the parent or child. 

5.2 Pipes 

Processes may communicate with related processes using the same system read and writ* 
calls that are used for file-system I/O. The call: 

filep pipe () 

returns a file descriptor filep and creates an inter-process channel called a pipe. This channel, 
like other open files, is passed from parent to child process in the image by the fork call. A 
read using a pipe file descriptor waits until another process writes using the file descriptor for 
the same pipe. At this point, data are passed between the images of the two processes. Neither 
process need know that a pipe, rather than an ordinary file, is involved. 

Although inter-process communication via pipes is a quite valuable tool (see Section 6.2), 
it is not a completely general mechanism, because the pipe must be set up by a common ances¬ 
tor of the processes involved. 

5.3 Execution of programs 

Another major system primitive is invoked by 

execute (file, arg t , arg^, .... arg n ) 

which requests the system to read in and execute the program named by file, passing it string 

arguments arg.. arg*.arg„. All the code and data in the process invoking execute is 

replaced from the file, but open files,. current directory, and inter-process relationships are 
unaltered. Only if the call fails, for example because file could not be found or because iu 
execute-permission bit was not set, does a return take place from the execute primitive; it 






resembles a “jump*' machine instruction rather than a subroutine calL 

5.4 Ptoccss synchronization 

Another process control system call: 
processid ■“ wait (status) 

causes its caller to suspend execution until one of its children has completed execution. Then 
wait returns the processid of the terminated process. An error return is taken if the calling 
process has no descendants. Certain status from the child process is also available. 

5.5 Termination 

Lastly: 
exit (status) 

terminates a process, destroys its image, closes its open files, and generally obliterates it The 
parent is notified through the wait primitive, and status is made available to it. Processes may 
also terminate as a result of various illegal actions or user-genera ted signals (Section vn 
below). 

VI. THE SHELL 

For most users, communication with the system is carried on with the aid of a program 
called the shell The shell is a command-line interpreter: it reads lines typed by the user and 
interprets them as requests to execute other programs. (The shell is described fully elsewhere, 9 
so this section will only the theory of its operation.) In simplest form, a command line 

consists of the command name followed by arguments to the command, all separated by spaces: 

' command arg^ arg 2 ... arg n 

The shell splits up the command name and the arguments into separate strings. Then a file 
with command is sought; command may be a path name including the character to 
specify any file in the system. If command is found, it is brought into memory and executed. 
The arguments collected by the shell are accessible to the command. When the command is 
fini<h^H, the shell resumes its own execution, and indicates its readiness to accept another com¬ 
mand by typing a prompt character. 

If file command cannot be found, the shell generally prefixes a string such as /bin/ to 
command and attempts again to find the file. Directory /bin contains commands intended to 
be generally used. (The sequence of directories to be searched may be changed by user 
request.) 

Standard I/O 

The discussion of I/O in Section III above seems to imply that every file used by a pro¬ 
gram must be opened or created by the p rog ra m in order to get a file descriptor for the file. 
Programs executed by the shell however, start off with three open files with file descriptors 0, 
1, and 2. As such a program begins execution, file .1 is open for writing, and is best understood 
as the standard output file. Except under circumstances indicated below, this file is the user’s 
terminal Thus programs that wish to write informative information ordinarily use file descrip¬ 
tor 1. Conversely, file 0 starts off open for reading, and programs that wish to read messages 
typed by the user read this file. 

The shell is able to change the standard assignments of these file descriptors from the 
user’s ter minal printer and keyboard. If one of the arguments to a command is prefixed by 
file descriptor 1 will, for the duration of the command, refer to the file named after the 
“>”. For example: 
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Is 

ordinarily lists, on the typewriter, the names, of the files in the current directory. The com¬ 
mand: 

Is > there 

creates a file called there and places the listing there. Thus the argument > there means “place 
output on there." On the other hand: 

ed 

ordinarily enters the editor, which takes requests from the user via his keyboard. The com¬ 
mand 

ed < script 

interprets script as a file of editor commands; thus < script means “take input from script. “ 

Although the file name following “<“ or “>“ appears to be an argument to the com¬ 
mand, in fact it is interpreted completely by the shell and is not passed to the command at alL 
Thus no special coding to handle I/O redirection is needed within each command; the com¬ 
mand need merely use the standard file descriptors 0 and l where appropriate. 

File descriptor 2 is* like file l, ordinarily associated with the terminal output stream. 
When an output-diversion request with “>" is specified, file 2 remains attached to the termi¬ 
nal, so that commands may produce diagnostic messages that do not silently end up in the out¬ 
put file. 

6.2 niters 

An extension of the standard I/O notion is used to direct output from one command to 
the input of another. A sequence of commands separated by vertical bars causes the shell to 
execute ail the commands simultaneously and to arrange that the s tand a r d output of each com¬ 
mand be delivered to the standard input of the next command in the sequence. Thus in the 
command line: 

Is 1 pr —21 opr 

Is lists the names of the files in the current directory; its output is passed to pr, which pa gin a t es 
its input with dated headings. (The argument “-2” requests double-column output.) Likewise, 
the output from pr is input to opr; this command spools its input onto a file for off-line print¬ 
ing. 

This procedure could have been carried out more clumsily by: 

Is >tempi 

pr -2 <tempi >temp2 
opr <temp2 

followed by removal of the temporary files. In the absence of the ability to redirect output and 
input, a still clumsier method would have been to require the Is command to accept user 
requests to paginate its output, to print in multi-column format, and to arrange that its output 
be delivered off-line. Actually it would be surprising, and in fact unwise for efficiency reasons, 
to expect authors of commands such as Is to provide such a wide variety of output options. 

A program such as pr which copies its standard input to its s t a nd a r d output (with process¬ 
ing) is called a filter. Some filters that we have found useful perform character transliteration, 
selection of lines according to a pattern, sorting of the input, and encryption and decryption. 
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(.3 Command separators; multitasking 

Another feature provided by the shell is relatively straightforward. Commands need not 
be on different lines; instead they may be separated by semicolons: 

Is; ed 

will first list the contents of the current directory, then enter the editor, 

A related feature is more interesting. If s command is followed by “ft,** the shell will not 
wait for the command to finish before prompting again; instead, it is ready immediately to 
accept a new command. For example: 

as source > output ft 

\ • 

causes source to be assembled, with diagnostic output going to output; no matter how long the 
assembly takes, the shell returns Immediately. When the shell does not wait for the completion 
of a command, the identification number of the process running that command is printed. This 
identification may be used to wait for the completion of the command or to terminate II The 
“ft” may be used several times in a line; 

as source >output ft Is > files ft 

does both the assembly and the listing in the background. In these examples, an output file 
other than the terminal was provided; if this had not been done, the outputs of the various 
commands would have been intermingled. 

The shell also allows parentheses in the above operations. For example: 

(date; Is) >x ft 

writes the current date and time followed by a list of the current directory onto the file x. The 
shell also returns immediately for another request 

6.4 The shell as a command; co mm a n d files 

The shell is itself a command, and may be called recursively. Suppose file tryout contains 
the lines: 

as source 

mv a. out testprog 

testprog 

The mv command causes the file a.ont to be renamed testprog. a.out is the (binary) output of 
the assembler, ready to be executed. Thus if the three lines above were typed on the keyboard, 
source would be assembled, the resulting program renamed testprog, and testprog executed. 
When the lines are in tryout, the command: 

sh < tryout 

would cause the shell sh to execute the commands sequentially. 

The shell has further capabilities, including the ability to substitute parameters and to con¬ 
struct argument lists from a spe ci fied subset of the file names in a directory. It also provides 
general conditional and looping constructions. 

6.f Implementation of the shell 

The outline of the operation of the shell can now be understood. Most of the time, the 
shell is waiting for the user to type a command. When the newline character ending the line is 
typed, the shell’s read call returns. The shell analyzes the command line, putting the argu¬ 
ments in a form appropriate for execute. Then fork is called. The child process, whose code of 
course is still that of the shell, attempts to perform an execute with the appropriate arguments. 
If successful, this will bring in and start execution of the program whose name was given. 
Meanwhile, the other process resulting from the fork, which is the parent process, waits for the 
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child process to die. When this happens, the shell knows the command is finished, so it types 
its prompt and reads the keyboard to obtain another command. 

Given this framework, the implementation of background processes is trivial; whenever a 
command line contains the shell merely refrains from waiting for the process that it 

created to execute the command. 

Happily, all of this mechanism meshes very nicely with the notion of standard input and 
output files. When a process is created by the fork primitive, it inherits not only the memory 
image of its parent but also all the files currently open in its parent, including those with file 
descriptors 0, 1, and 1 The shell, of course, uses these files to read command lines and to 
write its prompts and diagnostics, and in the ordinary case its children—the command 
programs—inherit them automatically. When an argument with or “>" is given, how¬ 
ever, the offspring process, just before it performs execute, makes the standard I/O file descrip¬ 
tor (0 or l, respectively) refer to the named file. This is easy because, by agreement, the smal¬ 
lest unused file descriptor is assigned when a.new file is opened (or created); it is only neces¬ 
sary to dose file 0 (or l) and open the named file; Because the process in which the command 
program runs simply terminates when it is through, the association between a file specified after 
“<" or v *>” and file descriptor 0 or l is ended automatically when the process dies. There¬ 
fore the shell need not know the actual names of the files that are its own standard input and 
output, because it need never reopen them. 

Filters are straightforward extensions, of standard I/O redirection with pipes used instead 
of files. 

In ordinary circumstances, the main loop of the. shell never terminates. (The main loop 
includes the branch of the return from fork belonging to the parent process; that is, the branch 
that does a wait, then reads another command line.) The one thing that causes the shell to ter¬ 
minate is discovering an end-of-file condition on its input file. Thus, when the shell is exe¬ 
cuted as a command with a given input file, as in; 

sh <comfile 

the commands in comfile will be executed until the end of comflle is reached; then the instance 
of the shell invoked by sh will terminate. Because this shell process is the child of another 
instance of the shell, the wait executed in the latter will return, and another command may 
then be processed. 

6.6 Initialization 

The in yane^ of the shell to which users type commands are themselves children of 
another process. The last step in the initialization of the system is the creation of a single pro¬ 
cess and the invocation (via execute) of a p r o gr a m called init. The role of init is to create one 
process for each te rminal c hann el- The various subinstances of init open the appropriate termi¬ 
nals for input and output on files 0, 1. and 2, waiting, if necessary, for carrier to be established 
on dial-up lines. Then a message is typed out requesting, that the user log in. When the user 
types a name or other identification, the appropriate instance of init wakes up, receives the 
log-in line, and reads a password file. If the user’s name is found, and if he is able to supply 
the correct password, Init changes to the user’s default current directory, sets the process’s user 
ID to that of the person logging in, and performs an execute of the sheiL At this point, the 
shell is ready to receive commands and the logging-in protocol is complete. 

Meanwhile, the mainstream path of init (the parent of all the subinstances of itself that 
will later become shells) does a wait. If one of the child processes terminates, either because a 
shell found an end of file or because a user typed an incorrect name or password, this path of 
init simply recreates the defunct process, which in turn reopens the appropriate input and out¬ 
put files and types another log-in message. Thus a user may log out simply by typing the end- 
of-file sequence to the shell. 
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6.7 Other programs as shell 

The shell as described above is designed to allow us er s full to the facilities of the 

system, because it will invoke the execution of any program with appropriate protection mode. 
Sometimes, however, a different interface to the system is desirable, and this feature is easily 
arranged for. 

Recall that after a user has successfully logged in by supplying a name and password, init 
ordinarily invokes the shell to interpret command lines. The user’s entry in the password file 
may contain the name of a program to be invoked after log-in instead of the shelL This pro¬ 
gram is free to interpret the user’s messages in any way it wishes. 

For example, the password file entries for users of a secretarial editing system might 
specify that the editor ed is to be used instead of the shell Thus when users of the editing sys¬ 
tem log in, they are inside the editor and can begin work immediately; also, they be 
prevented from invoking programs not intended for their use. In practice, it has proved desir¬ 
able to allow a temporary escape from the editor to execute the formatting program and other 
utilities. 

Several of the games (e.g., chess, blackjack, 3D tic-tac-toe) available on the system illus¬ 
trate a much more severely restricted environment For each of these, an entry exists in the 
password file specifying that the appropriate game-playing program is to be invoked instead of 
the shell. People who log in as a player of one of these games find themselves limited to the 
game and unable to investigate the (presumably more interesting) offerings of the Unix system 
as a whole. 

vn. TRAPS 

The PDP-11 hardware detects a number of program faults, such as references to non¬ 
existent memory, unimplemented instructions, and odd addresses used where an even a dd n rss 
is required. Such faults cause the processor to trap to a system routine. Unless other arranger 
ments have been made, an illegal action causes the system to terminate the process and to write 
its image on file core in the current directory. A debugger can be used to determine the y atg 
of the program at the time of the fault 

Programs that are looping, that produce unwanted output or about which the user has 
second thoughts may be halted by the use of the interrupt signal which is generated by typing 
the “delete” character. Unless special action has been taken, this signal simply causes the pro¬ 
gram to cease execution without producing a core file. There is also a quit signal used to force 
an image file to be produced. Thus programs that loop unexpectedly may be halted and the 
remains inspected without prearrangement. 

The hardware-generated faults and the interrupt and quit signals can, by request, be either 
ignored or caught by a process. For example, the shell ignores quits to prevent a quit from log¬ 
ging the user out The editor catches interrupts and returns to its command leveL This is use¬ 
ful for stopping long printouts without losing work in progress (the editor manipulates a copy of 
the file it is editing). In systems without floating-point hardware, unimplemented instructions 
are caught and floating-point instructions are interpreted. 

VIII. PERSPECTIVE 

Perhaps paradoxically, the succ e ss of the UNIX system is largely due to the fact that it was 
not designed to meet any predefined objectives. The first version was written when one of us 
(Thompson), dissatisfied with the available computer facilities, discovered a little-used pop-7 
and set out to create a more hospitable environment. This (essentially personal) effort was 
sufficiently successful to gain the interest of the other author and several colleagues, and later 
to justify the acquisition of the PDP-11/20, specifically to support a text editing and formatting 
system. When in turn the 11/20 was outgrown, the system had proved useful enough to per¬ 
suade management to invest in the PDP-ll/45, and later in the PDP-11/70 and Interdata 8/32 
machines, upon which it developed to its present form. Our goals throughout the effort, when 
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articulated at ail, have always been to build a comfortable relationship with the machine and to 
explore ideas and inventions in operating systems and other software. We have not been faced 
with the need to satisfy someone else’s requirements, and for this freedom we are grateful. 

Three considerations that influenced the design of UNIX are visible in retrospect. 

Fuse br rww* we are programmers, we naturally designed the system to make it easy to 
write, test, and run programs. The most important expression of our desire for programming 
convenience was that the system was arranged for interactive use, even though the original ver¬ 
sion only supported one user. We believe that a properly designed interactive system is much 
more productive and satisfying to use than a “batch” system. Moreover, such a system is 
rather easily adaptable to noointeractive use, while the converse is not true. 

Second: there have always been fairly severe size constraints on the system and its 
software. Given the partially antagonistic desires for reasonable efficiency and expressive 
power the size constraint has encouraged not only economy, but also a certain elegance of 
desigm This may be a thinly disguised, version of the “salvation through suffering” philosophy, 

but in our case it worked^ 

Third: nearly from the start, the system was able to, and did. maintain itself. This fact is 
more important than it might seem. If designers of a system are forced to use that system, 
they quickly become aware of its functional and superficial deficiencies and are strongly 
motivated, to correct them before it is too late. Because all source programs were always avafl- 
able and easily modified on-line, we were willing to revise and rewrite the system and its 
software when new ideas were invented, discovered, or suggested by others. 


The aspects of UNIX discussed in this paper exhibit dearly at least the first two of these 
design considerations. The interface to the file system, for example, is extremely convenient 
from a programming standpoint. The lowest possible interface level is designed to eliminate 
distinctions between the various devices and files and between direct and sequential access. No 
lar» “access method" routines, are required 10 insulate the programmer from the system calls; 
in fact, all user programs either call the system directly or use * small library program, less than 
a page long, that buffers a number of characters and reads or writes them all at once. 

Another important aspect of programming convenience is that there are no “control 
blocks” with a complicated structure partially- maintained by and dep ended o n by the file system 
or other system calls. Generally speaking, the contents of a program’s address space are the 
property of the program, and we have tried to avoid placing restrictions on the data structures 


within that address s p ace. 


Given the requirement that ail programs should be usable with any file or device as input 
or output, it is also desirable to push device-dependent considerations into the operating system 
itself. The only alternatives seem to be to load, with all programs, routines for dealing with 
device, which is expensive in space, or to depend on some means of dy n a mi cally linking 
to the routine appropriate to each device when it is acnudly needed, which is expensive either 
in overhead or in hardware. 


Likewise, the process-control scheme and the command interface have proved both con¬ 
venient and efficient. Because the shell operates as an ordinary, swappable user program, it 
consumes no “wired-down” space in the system proper, and it may be made as powerful as 
desired at little cost. In particular, given the framework in which the shell executes as a process 
that spawns other processes to perform co mman ds, the notions of I/O redirection, background 
processes, command files, and user-selectable system interfaces all become essentially trivial to 

implement. 


Influences 

The of UNIX lies not so much in aew inventions but rather in the full exploitation 

of a carefully selected set of fertile ideas, and especially in showing that they can be keys to the 
implementation of a small yet powerful oper a ti ng system. 
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The fork operation, essentially as we implemented it, was present in the GENIE time* 
sharing system. On a number of points we were influenced by Multics, which suggested the 
particular form of the I/O system calls” and both the name of the shell and its general func- 
uons. The notion that the shell should create a process for each command was also suggested 
to us by the .early design of Multics, although in that system it was later dropped for efficiency 
reaso n s. A similar scheme is used by TENEX . 12 1 

IX. STATISTICS 

The following numbers are presented to suggest the scale of the Research UNIX operation. 
Those of our users not involved in document preparation tend to use the system for program 
development, especially language work. There are few important “applications” programs. 
Overall, we have today: 

125 user population 

33 m a xim um simultaneous users 

1,630 directories 

28,300 files 

301,700 512-byte secondary storage blocks used 

There is a “background” process that runs at the lowest possible priority; it is used to soak up 
any idle CPU time. It has been used to produce a million-digit approximation to the constant l 
and other semi-infinite problems. Not counting this background work, we average daily: 


13,500 

commands 

9.6 

CPU hours 

230 

connect hours 

62 

different users 

240 

log-ins 
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ABSTRACT 

This paper describes in high-level terms the implementation of the 
resident UNDCf kernel This discussion is broken into three parts. The first pan 
describes how the UNIX system views processes, users, and programs. The 
second pan describes the I/O system. The last pan describes the Unix file sys¬ 
tem. 


1. INTRODUCTION 

The UNIX kernel consists of about 10,000 lines of C code and about 1,000 lines of assem¬ 
bly code. The assembly code can be further broken down into 200 lines included for the sake 
of efficiency (they could have been written in C) and 800 lines to perform hardware functions 

not possible in C 

This code represents 5 to 10 percent of what has been lumped into the broad expression 
“the UNIX operating system.” The kernel is the only UNIX code that cannot be substituted by a 
user to his own Mag. For this reason, the kernel should make as few real decisions as possi¬ 
ble. This does not mean to allow the user a million options to do the same thing. Rather, it 
means to allow only one way to do one thing, but have that way be the least-common divisor of 
all the options that might have been provided. 

What is or is not implemented in the kernel represents both a great responsibility and a 
great power. It is a soap-box platform on “the way things should be done.” Even so, if “the 
way” is too radical, no one will follow it. Every important decision was weighed carefully. 
Throughout, simplicity has been substituted for efficiency. Complex algorithms are used only if 
their complexity can be localized. 

2. PROCESS CONTROL 

In the UNIX system, a user executes programs in an environment called a user process. 
When a system function is required, the user process calls the system as a subroutine. At some 
point in this call, there is a distinct switch of environments. After this, the process is said to be 
a system process. In the normal definition of processes, the user and system processes are 
different phases of the same process (they never execute simultaneously). For protection, each 
system process has its own stack. 

The user process may execute from a read-only text segment, which is shared by all 
processes executing the same code. There is no Junctional benefit from shared-text segments. 
An efficiency benefit comes from the fact that there is no need to swap read-only segments out 
because the original copy on secondary memory is still current. This is a great benefit to 
interactive programs that tend to be swapped while waiting for terminal input. Furthermore, if 
two processes are executing simultaneously from the same copy of a read-only segment, only 
one copy needs to reside in primary memory. This is a secondary effect, because simultaneous 
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execution of a program is not common. It is ironic that this effect, which reduces the use of 
primary memory, only comes into play when there is an overabundance of primary memory, 
that is, when there is enough memory to keep waiting processes loaded. 

All current read-only text segments in the system are maintained from the text table. A 
text table entry holds the location of the text segment on secondary memory. If the segment is 
loaded, that table also holds the primary memory location and the count of the number of 
processes sharing this entry. When this count is reduced to zero, the entry is freed along with 
any primary and secondary memory holding the segment. When a process first executes a 
shared-text segment, a text table entry is allocated and the segment is loaded onto secondary 
memory. If a second process executes a text segment that is already allocated, the entry refer¬ 
ence count is simply incremented. 

A user process has some strictly private read-write data contained in its data segment. As 
far as possible, the system does not use the user’s data segment to hold system data. In partic¬ 
ular, there are no I/O buffers in the user address space. 

The user dan segment has two growing boundaries. One; increased automatically by the 
system as a result of memory faults, is used for a stack. The second boundary is only grown 
(or shrunk) by explicit requests. The contents of newly allocated primary memory is initialized 
to zero. 

Also associated and swapped with a process is a small fixed-size system data segment. 
This segment contains all the data about the process that the system needs only when the pro¬ 
cess is active. Examples of the kind of data contained in the system data segment are: saved 
central processor registers, open file descriptors, accounting information, scratch data area, and 
the stack for the system phase of the process. The system data segment is not addressable from 
the user process and is therefore protected. 

Last, there is a process table with one entry per process. This entry contains all the data 
needed by the system when the process is not active. Examples are the process’s name, the 
location of the other, segments, and scheduling information. The process table entry is allo¬ 
cated when the process is created, and freed when the process terminates. This process entry is 
always directly addressable by the kerneL 

Figure 1 shows the relationships between the various process control data. In a sense, the 
process table is the definition of all processes, because all the data associated with a process may 
be accessed starting from the process table entry. 



Fig. 1—Process control data structure. 










































2.1. Process creation and program execution 

Processes are created by the system primitive fork. The newly created process (child) is a 
copy of the original process (parent). There is no detectable sharing of primary memory 
between the two processes. (Of course, if the parent process was executing from a read-only 
text segment, the child will share the text segment.) Copies of all writable data segments are 
made for the child process. Files that were open before the fork are truly shared after the fork. 
The processes are informed as to their part in the relationship to allow them to select their own 
(usually non-identical) destiny. The parent may wait for the termination of any of its children. 

A process may exec a file. This consists of exchanging the current text and data segments 
of the process for new text and data segments specified in the file. The old segments are lost. 
Doing an exec does not change processes; the process that did the exec persists, but after the 
exec it is executing a different program. Files that were open before the exec remain open after 
the exec 

If a program, say the first pass of a compiler, wishes to overlay itself with another pro¬ 
gram, say the second pass, then it simply execs the second program. This is analogous to a 
“goto.** If a program wishes to regain control after exedng a second program, it should fork a 
child process, have the child exec the second program, and have the parent wait for the child. 
This is analogous to a “call.” Breaking up the call into a binding followed by a transfer is simi¬ 
lar to the subroutine linkage in SL-S. 1 

UL Swapping 

The major data associated with a process (the user data segment, the system data seg¬ 
ment, and the text segment) are swapped to and from secondary memory, as needed. The user 
data segment and the system data segment are kept in contiguous primary memory to reduce 
swapping latency. (When low-latency devices, such as bubbles, CCDs, or scatter/gather 
devices, , are used, this decision will have to be reconsidered.) Allocation of both primary and 
secondary memory is performed by the same simple first-fit algorithm. When a process grows, 
a new piece of primary memory is allocated. The contents of the old memory is copied to the 
new memory. The old memory is freed and the tables are updated. If there is not enough pri¬ 
mary memory, secondary memory is allocated instead. The process is swapped out onto the 
secondary memory, ready to be swapped in with its new sue. 

One separate process in the kernel, the swapping process, simply swaps the other 
processes in and out of primary memory. It examines the process table looking for a process 
that is swapped out and is ready to run. It allocates primary memory for that process and reads 
its segments into primary memory, where that process competes for the central processor with 
other loaded processes. If no primary memory is available, the swapping process makes 
memory available by examining the process table for processes that can be swapped out. It 
selects a process to swap out, writes it to secondary memory, frees the primary memory, and 
then goes back to look for a process to swap in. 

Thus there are two specific algorithms to the swapping process. Which of the possibly 
many processes that are swapped out is to be swapped in? This is decided by secondary storage 
residence time. The one with the longest time out is swapped in first. There is a slight penalty 
for larger processes. Which of the possibly many processes that are loaded is to be swapped 
out? Processes that are waiting for slow events (i.e., not currently running or waiting for disk 
I/O) are picked first, by age in primary memory, again with sue penalties. The other processes 
are examined by the same age algorithm, but are not taken out unless they are at least of some 
age. This adds hysteresis to the swapping and prevents total thrashing. 

These swapping algorithms are the most suspect in the system. With limited primary 
memory, these algorithms cause total swapping. This is not bad in itself, because the swapping 
does not impact the execution of the resident processes. However, if the swapping device must 
also be used for file storage, the swapping traffic severely impacts the file system traffic. It is 
exactly these small systems that tend to double usage of limited disk resources. 
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2,3. Synchronization and scheduling 

Process synchronization is accomplished by having processes wait for events. Events are 
represented by arbitrary integers. By convention, events are chosen to be addresses of tables 
associated with those events. For example, a process that is waiting for any of its children to 
terminate will wait for an event that is the address of its own process table entry. When a pro¬ 
cess terminates, it signals the event represented by its parent’s process table entry. Signaling an 
event on which no process is waiting has no effect. Similarly, signaling an event on which 
many processes are waiting will wake all of them up. This differs considerably from Dijkstra’s. 
P and V synchronization operations,* in that no memory is associated with events. Thus there 
need be no allocation of events prior to their use. Events exist simply by being used. 

On the negative side, because there is no memory associated with events, no notion of 
“how much” can be signaled via the event mechanism. For example, processes that want 
memory might wait on art event associated with memory allocation. When any amount of 
memory becomes available, the event would be signaled. All the competing processes would 
then wake up to fight over the new memory. (In reality, the swapping process is the only pro¬ 
cess that waits for primary memory to become available.) 

If an event occurs between the time a process decides to wait for that event and the time 
that process enters the wait state, then the process will wait on an event that has already hap¬ 
pened (and may never happen again). This race condition happens because there is no memory 
associated with the event to indicate that the event has occurred; the only action of an event is 
to change a set of processes from wait state to run state. This problem is relieved largely by the 
fact that proc e ss switching can only occur in the kernel by explicit ca lls to the event-wait 
mechanism. If the event in question is signaled by another process, then there is no problem. 
But if the event is signaled by a hardware interrupt, then special care must be taken. These 
synchronization races pose the biggest problem when UNIX is adapted to multiple-processor 
configurations. 3 

The event-wait code in the kernel is like a co-routine linkage. At any time, all but one of 
the processes has called event-wait. The remaining process is the one currently executing. 
When it call* event-wait, a process whose event has been signaled is selected and that process 
returns from its call to event-wait. 

Which of the ninabie processes is to run next? Associated with each process is a priority. 
The priority of a system process is assigned by the code issuing the wait on an event. This is 
roughly equivalent to the response that one would expect on such an event. Disk events have 
high priority, teletype events are low, and time-of-day events are very low. (From observation, 
the difference in system process priorities has little or no performance impact.) All user-process 
priorities are lower than the lowest system priority. User-process priorities are assigned by an 
algorithm based on the recent ratio of the amount of compute time to real time consumed by 
the process. A pro cess that has used a lot of compute time in the last real-time unit is assigned 
a low user priority. Because interactive processes are characterized by low ratios of compute to 
real time, interactive response is maintained without any special arrangements. 

The scheduling algorithm simply picks the process with the highest priority, thus picking 
all system processes first and user processes second. The compute-to-real-time ratio is updated 
every second. Thus, all other things being equal, looping user processes will be scheduled 
round-robin with a 1-second quantum. A high-priority process waking up will preempt a run¬ 
ning, low-priority process. The scheduling algorithm has a very desirable negative feedback 
character. If a process uses its high priority to hog the computer, its priority will drop. At the 
same time, if a low-priority process is ignored for a long time, its priority will rise. 

3. I/O SYSTEM 

The I/O system is broken into two completely separate systems: the block I/O system and 
the character I/O system. In retrospect, the names should have been “structured I/O” and 
“unstructured I/O,” respectively; while the term “block I/O” has some meaning, “character 
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I/O” is a complete misnomer. 

Devices are characterized by a major device number, a minor device number, and a class 
(block or character). For each class, there is an array of entry points into the device drivers. 
The major device number is used to index the array when calling the code for a particular 
device driver. The minor device number is passed to the device driver as an argument. The 
minor number has no significance other than that attributed to it by the driver. Usually, the 
driver uses the minor number to access one of several identical physical devices. 

The use of the array of entry points (configuration table) as the only connection between 
the system code and the device drivers is very important Early versions of the system had a 
much less formal connection with the drivers, so that it was extremely hard to handcraft 
differently configured systems. Now it is possible to create new device drivers in an average of 
a few hours. The configuration table in most cases is created automatically by a program that 
reads the system's parts list. 

3.1. Block I/O system 

The model block I/O device consists of randomly addressed, secondary memory blocks of 
512 bytes each. The blocks are uniformly addressed 0, 1,... up to the size of the device. The 
block device driver has the job of emulating this model on a physical device. 

The block I/O devices are accessed through a layer of buffering software. The system 
maintain* t list of buffers (typically between 10 and 70) each assigned a device name and a 
device address. This buffer pool constitutes a data cache for the block devices. On a read 
request, the cache is searched for the desired block. If the block is found, the data are made 
available to the requester without any physical I/O. If the block is not in the cache, the least 
recently used block in the cache is renamed, the correct device driver is called to fill up the 
renamed buffer, and then the data are made available. Write requests are handled in an analo¬ 
gous manner. The correct buffer is found and relabeled if n e cessa r y. The write is performed 
simply by marking the buffer as “dirty.” The physical I/O is then deferred until the buffer is 
renamed. 

The benefits in reduction of physical I/O of this scheme are substantial, especially consid¬ 
ering the file system implementation. There are, however, some drawbacks. The asynchronous 
nature of the algorithm makes error reporting and meaningful user error h a n dli n g almost 
impossible. The cavalier approach to I/O error handling in the UNIX system is partly due to the 
asynchronous nature of the block I/O system. A second problem is in the delayed writes. If 
the system stops unexpectedly, it is almost certain that there is a lot of logically complete, but 
physically incomplete, I/O in the buffers. There is a system primitive to flush all outstanding 
I/O activity from the buffers. Periodic use of this primitive helps, but does not solve, the prob¬ 
lem. Finally, the associativity in the buffers can alter the physical I/O sequence from that of 
the logical I/O sequence. This means that there are times when data structures on disk are 
inconsistent, even though the software is careful to perform I/O in the correct order. On non- 
random devices, notably magnetic tape, the inversions of writes can be disastrous. The prob¬ 
lem with magnetic tapes is “cured” by allowing only one outstanding write request per drive. 

3.2. Character I/O system 

The character I/O system consists of all devices that do not fall into the block I/O model. 
This indudes the “classical” character devices such as communications lines, paper tape, and 
line printers. It also includes magnetic tape and disks when they are not used in a stereotyped 
way, for example, 80-byte physical records on tape and track-at-a-time disk copies. In short, 
the character I/O interface means “everything other than block.” I/O requests from the user 
are sent to the device driver essentially unaltered. The implementation of these requests is, of 
course, up to the device driver. There are guidelines and conventions to help the implementa¬ 
tion of certain types of device drivers. 






3.2.1. Disk drivers 

Disk drivers are implemented with a queue of transaction records. Each record holds a 
read/write flag, a primary memory address, a secondary memory address, znd i \i*ns£tx by e 
count. Swapping is accomplished by passing such a record to the swapping device driven The 
block I/O interface is implemented by passing such records with requests to fill and empty sys¬ 
tem buffers. The character I/O interface to the disk drivers create a transacuon record that 
ooints directly into the user area. The routine that creates this record also insures that the user 
iTnot swapped during this I/O transaction. Thus by implemenung the general disk driver, it is 
possible to use the disk as a block device, a character device; and a swap device. The only 
really disk-specific code in normal disk drivers is the pre-sort of transactions to minimize 
latency for a particular device, and the actual issuing of the I/O request. 

3.2.2. Character lists 

Real character-oriented devices may be implemented using the common code to handle 
character lists. A character list is a queue of characters. One routine puts a character on a 
Another jea . chancier from a queue. It is also possible to ask how mam characters 
are currently on a queue. Storaje for all queues in the system comes from 
pool Putting a character on a queue will allocate space from the common pool and link the 
character onto the data structure defining the queue. Getting a character from a queue returns 
the corresponding space to the pool. 

A typical character-output device (paper tape punch, for example) is implemented by 
passing characters from the user onto a character queue until some maximum 
actersis on the queue. The I/O is prodded to start as soon as there is anything on the queue 
and, once started, it is sustained by hardware completion interrupts. Each u ™ e there is a com- 
nietLn inierrum. the driver gets the next character from the queue and sends it to the 
hardware. The number of characters on the queue is checked and, as the count falls through 
some intermediate level, an event (the queue address) is signaled. The process that is passm* 
characters from the user to the queue can be waiting on the event, and refill the queue to its 
maximum when the event occurs. 

A typical character input device (for example, a paper tape reader) is handled in a very 
similar manner. 

Another class of character devices is the terminals. A terminal is represented by three 
character queues. There are two input queues (raw and canonical) and an output queue. Char¬ 
acters going to the output of a terminal are handled by common code exactly as described 
above. The main difference is that there is also code to interpret the output stream as ASCII 
characters and to perform some translations, e.g., escapes for deficient terminals. Another 
common aspect of terminals is code to insert real-time delay after certain control characters. 

Input on terminals is a little different. Characters are collected from the terminal and 
placed on a raw input queue. Some device-dependent code conversion and escape interpreta¬ 
tion is handled here. When a line is complete in the raw queue, an event is signaled. The code 
catching this signal then copies a line from the raw queue to a canonical queue performing the 
character erase and line kill editing. User read requests on terminals can be directed at either 

the raw or canonical queues. 

3.2.3. Other character devices 

Finally there are devices that fit no general category. These devices are set up as charac¬ 
ter I/O drivers. An example is a driver that reads and writes unmapped primary memory as an 
I/O device. Some devices are too fast to be treated a character at time, but do not fit the disk 
I/O mold. Examples are fast communications lines and fast line printers. These devices either 
have their own buffers or “borrow” block I/O buffers for a while and then give them back. 
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4. THE FILE SYSTEM 

In the UNIX system, a file is a (one-dimensional) array of bytes. No other structure of 
files is implied by the system. Files are attached anywhere (and possibly multiply) onto a 
hierarchy of directories. Directories are simply files that users cannot write. For a further dis¬ 
cussion of the external view of files and directories, see Ref. 4. 

The UNIX file system is a disk data structure accessed completely through the block I/O 
system. As stated before, the canonical view of a “disk” is a randomly addressable array of 
512-byte blocks. A file system breaks the disk into four self-identifying regions. The first 
block (address 0) is unused by the file system. It is left aside for booting procedures. The 
second block (address l) contains the so-called “super-block.” This block, among other things, 
contains the size of the disk and the boundaries of the other regions. Next comes the i-list, a 
list of file definitions. Each file definition is a 64-byte structure, called an i-node. The offset of 
a particular i-node within the i-list is called its i-number. The combination of device name 
(major and minor numbers) and i-number serves to uniquely name a particular file. After the 
i-list, and to the end of the disk, come free storage blocks that are available for the contents of 
files. 

The free space on a disk is maintained by a linked list of available disk blocks. Every 
block in this chain contains a disk address of the next block in the chain. The remaining space 
contains the address of up to 50 disk blocks that are also free. Thus with one I/O operation, 
the system obtains 50 free blocks and a pointer where to find more. The disk allocation algo¬ 
rithms are very straightforward. Since all allocation is in fixed-size blocks and there is strict 
accounting of space, there is no need to compact or garbage collect. However, as disk space 
becomes dispersed, latency gradually increases. Some i nst al l ations choose to occasionally com¬ 
pact disk space to reduce latency. 

An i-node contains 13 disk addresses. The first 10 of these add r esses point directly at the 
first 10 blocks of a file. If a file is larger than 10 blocks (5,120 bytes), then the eleventh 
address points at a block that contains the addresses of the next 128 blocks of the file. If the 
file is still larger than this (70,656 bytes), then the twelfth block points at up to 128 blocks, 
each pointing to 128 blocks of the file. Files yet larger (8,459,264 bytes) use the thirteenth 
address for a “triple indirect” address. The algorithm ends here with the maximum file size of 
1,082,201,087 bytes. 

A logical directory hierarchy is added to this flat physical structure simply by adding a new 
type of file, the directory. A directory is accessed exactly as an ordinary file. It contains 16* 
-byte entries consisting of a 14-byte name and an i-number. The root of the hierarchy is at a 
known i-number (viz. 2). The file system structure allows an arbitrary, directed graph of direc¬ 
tories with regular files linked in at arbitrary places in this graph. In fact, very early UNIX sys¬ 
tems used such a structure. Administration of such a structure became so chaotic that later sys¬ 
tems were restricted to a directory tree. Even now, with regular files linked multiply into arbi¬ 
trary places in the tree, accounting for space has become a problem. It may become necessary 
to restrict the entire structure to a tree, and allow a new form of linking that is subservient to 
the tree structure. 

The file system allows easy creation, easy removal, easy random a cc ess i n g , and very easy 
space allocation. With most physical addresses confined to a small contiguous section of disk, it 
is also easy to dump, restore, and check the consistency of the file system. Large files suffer 
from indirect addre s sin g, but the cache prevents most of the implied physical I/O without 
adding much execution. The space overhead properties of this scheme are quite good. For 
example, on or.e particular file system, there are 25,000 files containing 130M bytes of data-file 
content. The overhead (i-node, indirect blocks, and last block breakage) is about 11.5M bytes. 
The directory structure to support these files has about 1,500 directories containing 0.6M bytes 
of directory content and about 0.5M bytes of overhead in accessing the directories. Added up 
any way, this comes out to less than a 10 percent overhead for actual stored data. Most sys¬ 
tems have this much overhead in padded trailing blanks alone. 






4.1. File system Implementation 

Because the i-node defines a file, the implementation of the file system centers around 
***»* ^ maintains a table of all active i-nodes. As a new file ts 
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The user process accesses the file system with certain primitives. The most common of 
these « 0 ^^ reed, write, seek, and close The dam structures mamtamed are shown 

in Fig. 1 



Fig. 2-Ftle system data structure. 

Tn the system data segment associated with a user, there is room for some (usually between 10 
and 50) open files. This open file table consists of pointers that can be used to access 
corresponding i-node table entries. Associated with each of these open filesis a current 
Doimer. This is a byte offset of the next read/write operation on the file. The system treats 
each read/write request as random with an implied seek to the I/O pointer. The user usually 
thinks of the file as sequential with the I/O pointer automatically counting the number of bytes 
;Kav, Sen rSj5X.cn from .he Sic. The user may. of course. perform random I/O by 
setting the I/O pointer before reads/writes. 

With file sharing, it is necessary to allow related processes to share a common I/O pointer 






























and yet have separate I/O pointers for independent processes that a cces s the same file. With 
these two conditions, the I/O pointer cannot reside in the i-node table nor can it .reside in the 
list of open files for the process. A new table (the open file table) was invented for the sole 
purpose of holding the I/O pointer. Processes that share the same open file (the result of 
forks) share a common open file table entry. A separate open of the same file will only share 
the i-node table entry, but will have distinct open file table entries. 

The main file system primitives are implemented as follows, open converts a file system 
path name into an i-node table entry. A pointer to the i-node table entry is placed in a newly 
created open, file table entry. A pointer to the file table entry is placed in the system data seg¬ 
ment for the process, create first creates a new i-node entry, writes the i-number into a direc¬ 
tory, and then builds the same structure as for an open, read and write just access the i-node 
entry as described above, seek simply manipulates the I/O pointer. No physical seeking is 
done, dose just frees the structures built by open and create. Reference counts are kept on 
the open file table entries and the i-node table entries to free these structures after the last 
reference goes away, onlink simply decrements the count of the number of directories point¬ 
ing at the given i-node. When the last reference to an i-node table entry goes away, if the i- 
node has no directories pointing to it, then the file is removed and the i-node is freed. This 
delayed removal of files prevents problems arising from removing active files. A file may be 
removed while still open. The resulting unnamed file vanishes when the file is dosed. This is 
a method of obtaining temporary files. 

There is a type of unnamed FIFO file called a pipe. Implementation of pipes consists of 
implied seeks before each read or write in order to implement first-in-first-out There are also 
checks and synchronization to prevent the writer from grossly outproducing the reader and to 
prevent the reader from overtaking the writer. 

4.2. Mounted file systems 

The file system of a UNIX system starts with some designated block device formatted as 
described above to contain a hierarchy. The root of this structure is the root of the UNIX file 
system. A second formatted block device may be mounted at any leaf of the current hierarchy. 
This logically extends the current hierarchy. The implementation of mounting is trivial. A 
mount table is maintained containing pairs of designated leaf i-nodes and block devices. When 
converting a path name into an i-node, a check is made to see if the new i-node is a designated 
leaf. If it is, the i-node of the root of the block device replaces it 

Allocation of space for a file is taken from the free pool on the device on which the file 
lives. Thus a file system consisting of many mounted devices does not have a common pool of 
free secondary storage space. This separation of space on different devices is ne ce ssa r y to allow 
easy unmounting of a device. 

4 .3. Other system functions 

There are some other things that the system does for the user—a little accounting, a little 
tracing/debugging, and a little access protection. Most of these things are not very well 
developed because our use of the system in computing science research does not need them. 
There are some features that are missed in some applications, for example, better inter-process 
communication. 

The UNIX kernel is an I/O multiplexer more than a complete operating system. This is as 
it should be. Because of this outlook, many features are found in most other operating systems 
that are missing from the UNIX kernel. For example, the UNIX kernel does not support file 
access methods, file disposition, file formats, file maximum size, spooling, command language, 
logical records, physical records, assignment of logical file names, logical file names, more than 
one character set, an operator’s console, an operator, log-in, or log-out. Many of these things 
are symptoms rather than features. Many of these things are implemented in user software 
using the kernel as a tool. A good example of this is the command language . 5 Each user may 
have his own command language. Maintenance of such code is as easy as maintaining user 
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code. The idea of implementing “system” code with general user primitives comes directly 
from MULTKS> 
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This paper fives an overview of the workings of the UNDCt I/O system. It was written 
with an eye toward providing guidance to writers of device driver routines, and is oriented more 
toward describing the environment and nature of device drivers than the implementation of 
that pan of the file system which deals with ordinary files. 

It is assumed that the reader has a good knowledge of the overall structure of the file sys¬ 
tem as discussed in the paper “The UNIX Time-sharing System.” A more detailed discussion 
appears in “UNIX Implementation;” the current document restates pans of that one, but is 
still more det ailed, It is most useful in conjunction with a copy of the system code, since it is 
basically an exegesis of that code. 

Device Classes 

There are two classes of device: Mock and character. The block interface is suitable for 
devices like disks, tapes, and DECtape which work, or can work, with addressible 512-byte 
blocks. Ordinary magnetic tape Just barely fits in this category, since by use of forward and 
backward spacing any block can be read, even though blocks can be written only at the end of 
the tape. Block devices can at least potentially contain s mounted file system. The interface to 
block devices is very highly structured; the driven for these devices share a great many rou¬ 
tines as well as a pool of buffers. 

Character-type devices have a much more straightforward interface, although more work 
must be done by the driver itself. 

Devices of both types are named by a major and a minor device number. These numbers 
are generally stored as an integer with the minor device number in the low-order 8 bits and the 
major device number in the next-higher 8 bits; macros major and minor are available to access 
these numbers. The major device number selects which driver will deal with the device; the 
minor device number is not used by the rest of the system but is passed to the driver at 
appropriate times. Typically the minor number selects a subdevice attached to a given con¬ 
troller, or one of several similar hardware interfaces. 

The major device numbers for block and character devices are used as indices in separate 
tables; they both start at 0 and therefore overlap. 

Overview of I/O 

The purpose of the open and c rent system calls is to set up entries in three separate system 
tables. The first of these is the ujofile table, which is stored in the system’s per-process data 
area il This table is indexed by the file descriptor returned by the open or creat, and is accessed 
during a read, write, or other operation on the open file. An entry contains only a pointer to the 
corresponding entry of the file table, which is a per-system data base. There is one entry in the 
file table for each instance of open at creat. This table is per-system because the same instance 
of an open file must be shared among the several processes which can result from forks after 
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ihe file is opened. A file table entry contains flags which indicate whether the file was open for 
reading or writing or is a pipe, and a co.unt which is used to decide when all processes using the 
entry have terminated or dosed the file (so the entry can be abandoned). There is also a 32-bit 
file offset which is used to indicate where in the file the next read or write will take place. 
Finally, there is a pointer to the entry for the file in the inode table, which contains a copy of 
the file’s i-node. , 

Certain open files can be designated “multiplexed” files, and several other flags apply to 
such channels. In such a case, instead of an offset, there is a pointer to an assodated multiplex 
channel table. Multiplex channels will not be discussed here. 

An entry in the file table corresponds precisely to an instance of open or creat; if the same 
file is opened several times, it will have several entries in this table. However, there is at most 
one entry in the inode table for a given file. Also, a file may enter the inode table not only 
because it is open, but also because it is the current directory of some process or because it is a 
special file containing a currently-mounted file system. 

An entry in the inode table differs somewhat from the corresponding i-node as stored on 
the disk; the modified and accessed times are not stored, and the entry is augmented by a flag 
word containing information about the entry, a count used to determine when it may be 
allowed to disappear, and the device and i-number whence the entry came. Also, the several 
block numbers that give addressing information for the file are expanded from the 3-byte, 
compressed formal used on the disk to full long quantities. 

During the processing Of an open or creat call for a special file, the system always calls the 
device’s open routine to allow for any special processing required (rewinding a tape, turning on 
the data-terminal-ready lead of a modem, etc.). However, the dose routine is called only when 
the last process closes a file, that is, when the i-node table entry is being deallocated. Thus it is 
not feasible for a device to maintain, or depend on, a count of its users, although it is quite 
possible to implement an exclusive-use device which cannot be reopened until it has been 
dosed. 

When a read or write takes place, the user’s arguments and the file table entry are used to 
set up the variables u.u_base, u.ujcount. and u.uyjffset which respectively contain the (user) 
a ri dr frc of the I/O target" area, the”byte-count for the transfer, and the current location in the 
file. If the file referred to. is a character-type special file, the appropriate read or write routine is 
called; it is responsible for transferring data and updating the count and current location 
appropriately as discussed below. Otherwise, the current location is used to calculate a logical 
block number in the file. If the file is an ordinary file the logical block number must be 
mapped (possibly using indirect blocks) to a physical block number, a block-type special file 
need not be mapped. This mapping is performed by the bmap routine. In any event, the 
resulting physical block number is used, as discussed below, to read or write the appropriate 
device. 

Character Device Drivers 

The cdevsw table specifies the interface routines present for character devices. Each dev¬ 
ice provides five routines: open, dose, read, write, and spedal-function (to implement the ioctl 
system call). Any of these may be missing. If a call on the routine should be ignored, (e.g. 
open on non-exclusive devices that require no setup) the cdevsw entry can be given as nulldev ; if 
it should be considered an error, (e.g. write on read-only devices) nodev is used. For terminals, 
(jjg cdevsw structure also contains a pointer to the tty structure associated with the terminal. 

The open routine is called each time the file is opened with the full device number as 
argument. The second argument is a flag which is non-zero only if the device is to be written 
upon. 

The close routine is called only when the file is closed for the last time, that is when the 
very last process in which the file is open closes it. This means it is not possible for the driver 
to maintain its own count of its users. The first argument is the device number, the second is a 




flag which is non-zero if the file was open for writing in the process which performs the final 

dose. 

When write is called, it is supplied the device as argument. The per-user variable 
u.ujnunt has been set to the number of characters indicated by the user, for character devices, 
this number may be 0 initially. u.ujbase is the address supplied by the user from which to start 
taking characters. The system may call the routine internally, so the flag u.ujegflg is supplied 
that indicates, if on, that i utjbase refers to the system address space instead of~the user's. 

The write routine should copy up to u.ujcount characters from the user's buffer to the 
device, decrementing u.account for each character passed. For most drivers, which work one 
character at a time, the routine cpassf ) is used to pick up characters from the user's buffer. 
Successive calls on it return the characters to be written until u.uj:ount goes to 0 or an error 
occurs, when it returns —1. Cpass takes care of interrogating u.u_segflg and updating u.u_count. 

Write routines which want to transfer a probably targe number of characters into an inter¬ 
nal buffer may also use the routine iomove(buffer, offset, count, flag) which is faster when many 
characters must be moved, lomove transfers up to count characters into the buffer sorting offset 
bytes from the start of the buffer, flag should be WRITE (which is 0) in the write case. Cau¬ 
tion: the caller is responsible for making sure the count is not too large and is non-zero. As an 
efficiency note, iornove is much slower if any of buffer+oflset, count or u.u_base is odd. 

The device’s read routine is called under conditions similar to write, except that u.u_count 
is guaranteed to be non-zero. To return characters to the user, the routine passc(c) is available; 
it takes care of housekeeping like cpass and returns -1 as the last character specified by 
u.ujcount is returned to the user, before that time, 0 is returned, lomove is also usable as with 
write; the flag should be B_READ but the same cautions apply. 

The "special-functions” routine is invoked by the say and grty system calls as follows: (~p) 
(dev, v) where p is a pointer to the device’s routine, dev is the device number, and v is a vector. 
In the gtty case, the device is supposed to place up to 3 words of status information into the 
vector, this will be returned to the caller. In the stty case, v is 0; the device should take up to 3 
words of control information from the array u.ujsrg[0...2J. 

Finally, each device should have appropriate interrupt-time routines. When an interrupt 
occurs, it is turned into a C-compatible call on the devices’s interrupt routine. The interrupt- 
catching' mechanism makes the low-order four bits of the “new PS” word in the trap vector for 
the interrupt available to the interrupt handler. This is conventionally used by driven which 
deal with multiple similar devices to encode the minor device number. After the interrupt has 
been processed, a return from the interrupt handler will return from the interrupt itself. 

A number of subroutines are available which are useful to character device drivers. Most 
of these handlers, for example, need a place to buffer characters in the internal interface 
between their “top half’ (read/write) and “bottom half” (interrupt) routines. For relatively 
low data-rate devices, the best mechanism is the character queue maintained by the routines 
getc and putc. A queue header has the structure 

struct [ 


int 

c_ar. 

/• character count ’/ 

char 

“c cf; 

/• first character •/ 

char 

•c“d; 

/• last character V 





A character is placed on the end of a queue by putcic, dequeue) where c is the character and 
queue is the queue header. The routine returns —1 if there is no space to put the character, 0 
otherwise. The first character on the queue may be retrieved by getc(&queue) which returns 
either the (non-negative) character or —1 if the queue is empty. 

Notice that the space for characters in queues is shared among all devices in the system 
and in the standard system there are only some 600 character slots available. Thus device 
handlers, especially write routines, must take care to avoid gobbling up excessive numbers of 
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characters. 

The other major help available to device handlers is the sleep-wakeup mechanism. The 
call sleep(event, priority) causes the process to wait (allowing other processes to run) until the 
event occurs; at that 'time, the process is marked ready-to-run and the call will return when 
there is no process with higher priority. 

The call wakeup(ev^nt) indicates that the event has happened, that is, causes processes 
sleeping on the event to be awakened. The event is an arbitrary quantity agreed upon by the 
sleeper and the waker-up. By convention, it is the address of some data area used by the 
driver, which guarantees that events are unique. 

Processes sleeping on an event should not assume that the event has really happened; 
they should check that the conditions which caused them to sleep no longer hold. 

Priorities can range from 0 to 127; a higher numerical value indicates a less-favored 
scheduling situation. A distinction is made between processes sleeping at priority less than the 
parameter PZERO and those at numerically larger priorities. The former cannot be interrupted 
by signals, although it is conceivable that it may be swapped out. Thus it is a bad idea to sleep 
with priority less than PZERO on an event which might never occur. On the other hand, calls 
to sleep with larger priority may never return if the process is terminated by some signal in the 
meantime. Incidentally, it is a gross error to call sleep in a routine called at interrupt time, 
since the process which is running is almost certainly not the process which should go to sleep. 
Likewise, none of the variables in the user area “u.” should be touched, let alone changed, by 
an interrupt routine. 

If a device driver wishes to wait for some event for which it is inconvenient or impossible 
to supply a wakeup . (for example, a device going on-line, which does not generally cause an 
interrupt), the call sleep(dlbolt. priority) may be given. Lbolt is an external cell whose address is 
awakened once every 4 seconds by the clock interrupt routine. 

The routines spl4( ). spl5( ), spl6( ). spl7( ) are available to set the processor priority level 
as indicated to avoid inconvenient interrupts from the device. 

If a device needs to know about real-time intervals, then timeout(func. arg, interval) will be 
useful. This routine arranges that after interval sixtieths of a second, the func will be called with 
arg as argument, in the style ('June)(arg). Timeouts are used, for example, to provide real¬ 
time delays after function characters like new-line and tab in typewriter output, and to ter¬ 
minate an attempt to read the 201 Dataphone dp if there is no response within a specified 
number of seconds. Notice that the number of sixtieths of a second is limited to 32767. since 
it must appear to be positive, and that only a bounded number of timeouts can be going on at 
once. Also, the specified func is called at dock-interrupt time, so it should conform to the 
requirements of interrupt routines in general. 

The Block-device Interface 

Handling of block devices is mediated by a collection of routines that manage a set of 
buffers containing the images of blocks of data on the various devices. The most important 
purpose of these routines is to assure that several processes that access the same block of the 
same device in multiprogrammed fashion maintain a consistent view of the data in the block. 
A secondary but still important purpose is to increase the efficiency of the system by keeping 
in-core copies of blocks that are being accessed frequently. The main data base for this 
mechanism is the table of buffers but'. Each buffer header contains a pair of pointers (bjorw, 
b back) which maintain a doubly-linked list of the buffers associated with a particular block 
device, and a pair of pointers (av J'orw. avjback) which generally maintain a doubly-linked list 
of blocks which are “free,” that is, eligible to be reallocated for another transaction. Buffers 
that have I/O in progress or are busy for other purposes do not appear in this list. The buffer 
header also contains the device and block number to which the buffer refers, and a pointer to 
the actual storage associated with the buffer. There is a word count which is the negative of the 
number of words to be transferred to or from the buffer, there is also an error byte and a 
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residual word count used to communicate information from an I/O routine to its caller. 
Finally, there is a flag word with bits indicating the status of the buffer. These flags will be dis¬ 
cussed below. 

Seven routines constitute the most important part of the interface with the rest of the sys¬ 
tem. Given a device and block number, both bread and getblk return a pointer to a buffer 
header for the block; the difference is that bread is guaranteed to return a buffer actually con¬ 
taining the current data for the block, while getblk returns a buffer which contains the data in 
the block only if it is already in core (whether it is or not is indicated by the BJDONEyiv. see 
below). In either case the buffer, and the corresponding device block, is made “busy,” so that 
other processes referring to it are obliged to wait until it becomes free. Getblk is used, for 
example, when a block is about to be totally rewritten, so that its previous contents are not use¬ 
ful; still, no other process can be allowed to refer to the block until the new data is placed into 

it. 

The breada routine is used to implement read-ahead, it is logically similar to bread, but 
takes as an additional argument the number of a block (on the same device) to be read asyn¬ 
chronously after the specifically requested block is available. 

Given a pointer to a buffer, the brelse routine makes the buffer again available to other 
processes. It is called, for example, after data has been extracted following a bread. There are 
three subtly-different write routines, all of which take a buffer pointer as argument, and all of 
which logically release the buffer for use by others and place it on the free list Bwrite puts the 
buffer on the appropriate device queue, waits for the write to be done, and sets the user’s error 
flag if required. Bawrite places the buffer on the device’s queue, but does not wait for comple¬ 
tion, so that errors cannot be reflected directly to the user. Bdwrite does not start any I/O 
operation at all, but merely marks the buffer so that if it happens to be grabbed from the free 
list to contain data from some other block, the data in it will first be written out. 

Bwrite is used when one wants to be sure that I/O takes place correctly, and that errors are 
reflected to the proper user; it is used, for example, when updating i-nodes. Bawrite is useful 
when more overlap is desired (because no wait is required for I/O to finish) but when it is rea¬ 
sonably certain that the write is really required. Bdwrite is used when there is doubt that the 
write is needed at the moment For example, bdwrite is called when the last byte of a write sys¬ 
tem call falls short of the end of a block, on the assumption that another write will be given 
soon which will re-use the same block. On the other hand, as the.end of a block is passed, 
bawrite is called, since probably the block will not be accessed again soon and one might as well 
start the writing process as soon as possible. 

In any event notice that the routines getblk and bread dedicate the given block exclusively 
to the use of the caller, and others wait, while one of brelse. bwrite. bawrite. or bdwrite 
must eventually be called to free the block for use by others. 

As mentioned, each buffer header contains a flag word which indicates the status of the 
buffer. Since they provide one important channel for information between the drivers and the 
block I/O system, it is important to understand these flags. The following names are manifest 
constants which select the associated flag bits. 

. B READ This bit is set when the buffer is handed to the device strategy routine (see below) 
to indi cate a read operation. The symbol B_ WRITE is defined as 0 and does not 
define a flag ; it is provided as a mnemonic convenience to callers of routines like 
swap which have a separate argument which indicates read or write. 

B DONE This bit is set to 0 when a block is handed to the the device strategy routine and is 
turned on when the operation completes, whether normally as the result of an error. 
It is also used as part of the return argument of getblk to indicate if 1 that the 
returned buffer actually contains the data in the requested block. 
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B ERROR This bit may be set to l when fl_0O/V£is set to indicate that an I/O or other error 
occurred. If it is set the bjrror byte of the buffer header may contain an error code 
if it is non-iero. If bjrror is 0 the nature of the error is not specified. Actually no 
driver at present sets bjrror; the latter is provided for a future improvement 
whereby a more detailed error-reporting scheme may be implemented. 

B BUSY This bit indicates that the buffer header is not on the free list, i.e. is dedicated to 
someone’s exclusive use. The buffer still remains attached to the list of blocks asso¬ 
ciated with its device, however. When getblk (or bread, which calls it) searches the 
buffer list for a given device and finds the requested block with this bit on, it sleeps 
until the bit dears. 

B PHYS This bit is set for raw I/O transactions that need to allocate the Unibus map on an 
11/70. 

B MAP This bit is set on buffers that have the Unibus map allocated, so that the lodone rou¬ 
tine knows to deallocate the map. 

B WANTEDThis Sag is used in conjunction with the B^BUSY bit. Before sleeping as described 
just above, getblk sets this flag. Conversely, when the block is freed and the busy bit 
goes down (in brelse) a wakeup is given for the block header whenever BLASTED 
is on. This strategem avoids the overhead of having to call wakeup every time a 
buffer is freed on the chance that someone might want it. 

B AGE This bit may be set on buffers just before releasing them; if it is on, the buffer is 
placed at the head of the free list, rather than at the tail. It is a performance heuris¬ 
tic used when the caller judges that the same block will not soon be used again. 

B ASYNCThis bit is set by bawrite to indicate to the appropriate device driver that the buffer 
should be released when the write has been finished, usually at interrupt time. The 
difference between bwrite and bawrite is that the former starts I/O, waits until it is 
done, and frees the buffer. The latter merely sets this bit and starts I/O. The bit 
indicates that relse should be called for the buffer on completion. 

B DELWRTThis bit is set by bdwrite before releasing the buffer. When getblk. while searching 
for a free block, discovers the bit is 1 in a buffer it would otherwise grab, it causes 
the block to be written out before reusing it. 

Block Device Drivers 

The bdevsw table contains the names of the interface routines and that of a table for each 
block device. 

Just as for character devices, block device drivers may supply an open and a dose routine 
called respectively on each open and on the final close of the device. Instead of separate read 
and write routines, each block device driver has a strategy routine which is called with a pointer 
to a buffer header as argument. As discussed, the buffer header contains a read/write flag, the 
core address, the block number, a (negative) word count, and the major and minor device 
number. The role of the strategy routine is to carry out the operation as requested by the 
information in the buffer header. When the transaction is complete the B_DOSE (and possibly 
the B_ERROR) bits should be set. Then if the BJSYNC bit is set, brelse should be called; 
otherwise, wakeup. In cases where the device is capable, under error-free operation, of 
transferring fewer words than requested, the device’s word-count register should be placed in 
the residual count slot of the buffer header, otherwise, the residual count should be set to 0. 
This particular mechanism is really for the benefit of the magtape driver, when reading this 
device records shorter than requested are quite normal, and the user should be told the actual 
length of the record. 

Although the most usual argument to the strategy routines is a genuine buffer header 
allocated as discussed above, ail that is actually required is that the argument be a pointer to a 
place containing the appropriate information. For example the swap routine, which manages 
movement of core images to and from the swapping device, uses the strategy routine for this 
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device. Care has to be taken that no extraneous bits get turned on in the flag word. 

The device’s table specified by bdevsw has a byte to contain an active flag and an error 
count, a pair of links which constitute the head of the chain of buffers for the device (bJorw, 
b back), and a first and last pointer for a device queue. Of these things, ail are used solely by 
the device driver itself except for the buffer-chain pointers. Typically the flag encodes the state 
of the device, and is used at a minimum to indicate that the device is currently engaged in 
transferring information and no new command should be issued. The error count is useful for 
counting retries when errors occur. The device queue is used to remember stacked requests; in 
the simplest case it may be maintained as a first-in first-out list. Since buffers which have been 
handed over to the strategy routines are never on the list of free buffers, the pointers in the 
buffer which maintain the free list (avJorw, avjback) are also used to contain the pointers 
which maintain the device queues. 

A couple of routines are provided which are useful to block device drivers, iodone(bp) 
arranges that the buffer to which bp points be released or awakened, as appropriate, when the 
strategy module has finished with the buffer, either normally or after an error. (In the latter 
case the B_ERROR bit has presumably been set.) 

The routine geterror(bp) can be used to examine the error bit in a buffer header and 
arrange that any error indication found therein is reflected to the user. It may be called only in 
the non-interrupt part of a driver when I/O has completed (B_DONE has been set). 

Raw Block-device I/O 

A scheme has been set up whereby block device drivers may provide the ability to 
transfer information directly between the user’s core image and the device without the use of 
buffers and in blocks as large as the caller requests. The method involves setting up a 
character-type special file corresponding to the raw device and providing read and write routines 
which set up what is usually a private, non-shared buffer header with the appropriate informa¬ 
tion and call the device’s strategy routine. If desired, separate open and dose routines may be 
provided but this is usually unnecessary. A special-function routine might come in handy, 
especially for magtape. 

A great deal of work has to be done tp generate the “appropriate information” to put in 
the argument buffer for the strategy module; the worst part is to map relocated user addresses 
to physical addresses. Most of this work is done by physio(strat, bp, dev, rw) whose arguments 
are the name of the strategy routine strat, the buffer pointer bp, the device number dev, and a 
read-write flag rw whose value is either B_READ or B_ WRITE. Physio makes sure that the 
user’s base address and count are even (because most devices work in words) and that the core 
area affected is contiguous in physical space; it delays until the buffer is not busy, and makes it 
busy while the operation is in progress; and it sets up user error return information. 
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Display Editing with VI 


Vi (visual) is a display oriented interactive text editor. When using vi the 
screen of your terminal acts as a window into the file which you are editing. 
Changes which you make to the file are reflected in what you see. 

Using vi you can insert new text at any place in the file quite easily. Most of the 
commands to vi move the cursor around in the file. There are commands to 
move the cursor forward and backward in units of characters, words, sentences 
and paragraghs. A small set of operators, like d for delete and c for change, are 
combined with the motion commands to form opterations such as delete word 
or change paragraph, in a simple and natural way. This regularity and the 
mnemonic assignment of commands to keys makes the editor command set 
easy to remember and to use. 

Vt will work on a large number of display terminals, and new terminals are easily 
driven after editing a terminal description file. While it is advantageous to have 
an intelligent terminal which can locally insert and delete lines and characters 
from the display, the editor will function quite well on dumb terminals over slow 
phone lines. The editor makes allowance for the low bandwidth in these situa¬ 
tions and uses smaller window sizes and different display updating algorithms to 
make best use of the limited speed available. 

It is also possible to use the command set of vi on hardcopy terminals, storage 
tubes and "glass tty’s" using a one line editing window; thus vi’s command set is 
available on all terminals. The full command set of the more traditional, line 
oriented editor ex is available within vi; it is quite simple to switch between the 
two modes of editing. 
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1. Getting started 

This document provides a quick introduction to w. (Pronounced vet-rye.) You should be 
running *»' on a file you are familiar with while you are reading this. The first part of this docu¬ 
ment (sections 1 through 5) describes the basics of using w. Some topics of special interest are 
presented in section 6. and some nitty-gritty details of how the editor fu n c t i on s are saved for 
section 7 to avoid cluttering the presentation here. 

There is also a short appendix here, which gives for each character the special meanings 
which this cbmas: has In vi Attached to this document should be a quick reference card. 
This card yirnmariTM the commands of w in a very compact format. You should have the card 
handy while you are learning v». 

1.1. Specifying terminal type 

Before you can start w you must tell the system what kind of terminal you are using. 
Here is a (necessarily incomplete) list of terminal type codes. If your terminal does not appear 
here, you should consult with one of the staff members on your system to find out the code for 
your terminal. If your terminal does not have a code, one can be assigned and a description for 
the terminal can be created. 


Cade 

Full name 

Type 

2621 

Hewlett-Packard 2621 A/P 

Intelligent 

2645 

Hewlett-Packard 264x 

Intelligent 

act4 

Micro term ACT-IV 

Dumb 

act5 

Micro term ACT-V 

* Dumb 

admSa 

Lear Siegler ADM-3a 

Dumb 

adm31 

Lear Siegler ADM-31 

Intelligent 

clOO 

Human Design Concept 100 

Intelligent 

dml520 

Datamedia 1520 

Dumb 

dm2500 

Datamedia 2500 

Intelligent 

dm3025 

Datamedia 3025 

Intelligent 

fox 

Perkin-Elmer Fox 

Dumb 

hi 500 

Hazel tine 1500 

Intelligent 

hl9 

Heath kit hi 9 

Intelligent 

1100 

Infoton 100 

Intelligent 

mime 

Imitating a smart atr.4 

Intelligent 
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*52 
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Intelligent 

Dumb 


Teleray 1061 

DecVT.« 

Suppose for example that you have a Hewlett-Packard HP2621A terminal. The code used 
Py tjse system for this terminal is ‘2621’. la this cue you can use one of the following com* 
goods to tell the system the type of your terminal: 

* setter TOM 2621 

This command works with the shell ah on both version 6 and 7 systems. If you are using the' 
standard version 7 shell then you should five the commands 

STOM-2621 
S expect TERM 

If you went tc.irrange to have your termini! type set up automatically when you lof in. 
you can use the otr program. If you dial in on a mime, but often use hardwired ports, s typical 
tine for your ,iogw file (if you use ah) would be 

setttrr TI31M 'tset - -d mime' 
or for your jnfik file (if you use sh) 

TX&M«*'tset - —d mime' 

Tstt knows which t amsais are hardwired to each port snd needs only to be told that when you 
dial in you era probably on a mime. 7*er is usually used to change the erase and kill character s, 
too. 

UL Editing, a file 

After — the system which kind of terminal you have, you should make a copy of a 
file you are with, and run w on this file, giving the co mm a n d 

% ri name 

replacing name with the name of the copy file you just created. The screen should dear and the 
text of your file should appear on the screen. If something else happens refer to the footnote.? 

U. The editor's copy: the buffer 

The editor does not directly modify the file which you are editing Rather, the editor 
twiner * copy of this file, in a place called the buffer. and remembers the file's name. You do 
not affect the contents of the file unless and until you write the changes you make back into the 
original file. 


t if you pvt to* system tn i ncom e lermuai type code then the editor may lave just made t mess out o f 
your screen. This happens when it sends control codes for one kind of terminei to some other kind of terrm- 
oaL In this case mi the keys a (colon and the q key) sad then hit the UTUIN key. This should set you beat 
to the commend level interpreter. Figure out whet you did wrong (ask someone else if necessary) and try 

spin 

Another thing which an jo wrong is that you typed the wrong Alt name tnd the editor just pnmed an 
error ‘diagnostic. In this case you should follow the shove p rocedure for itttmg out of the editor, snd try 
stain this time spelling the Ale name correctly. 

If the eaitor doesn't seem to respond to the commends which you type here, try sending an interrupt u> it 
by hitting the OG. or *us key on your terminei and then hitting the commend again followed by a carnage 
ret urn . 
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1.4. Notttionil conventions 

In our examples, input which must be typed as is will be presented in bold face. Text 
which should be replaced with appropriate input will be given in italics. We will represent spe¬ 
cial characters in small capitals. 

li. Arrow keys 

The editor command set is independent of the terminal you are using. On most terminals 
with cursor positioning keys, these keys will also work within the editor. If you don’t have cur¬ 
sor positioning keys, or even if you do, you can use the b J k and 1 keys as cursor positioning 
keys (these are labelled with arrows on an admSa). * 

(Particular note for the HP2621: on this terminal the function keys must be shifted (ick) 
to send to the maebina. otherwise they only act locally. Unshifted use will leave the cursor 
positioned in cor rectly.) 

1.6. Special characters: ESC. at and DEL 

Several of t hese special characters are very important, so be sure to find them right now. 
Look on your keyboard for a key labelled ESC or aLT. U should be near the upper left comer of 
your terminal. Try hitting this key a few times. The editor will ring the bell to indicate that it 
is in a quiescent state.* Partially formed commands are cancelled by ESC. and when you insert 
text in the file you end the text insertion with ESC This key is a fairly harmless one to hit. so 
you can just hit it if you don’t know what is going on until the editor rings the belL 

The at or RETURN key is important be cau se it is used to ter min ate certain com man ds. It 
is usually at the right side of the keyboard, and is the same command used at the end of each 
shell command. 

Another very useful key is the DEL or RUB key, which generates an interrupt, telling the 
editor to stop what it is doing. It is a forceful way of making the editor listen to you. or to 
return it to the quiescent sate if you don’t know or don’t like what is going on. Try hitting the 
♦/» key on your terminal. This key is used when you want to specify a string to be searched for. 
The cursor should now be positioned at the bottom line of the terminal after a 7* printed as a 
prompt. You can get the cursor back to the current position by hitting the DEL or rub key: try 
this now.* From now on we will simply refer to hitting the DEL or RUB key as “sending an 

interrupt.""* 

The editor often echoes your commands on the last line of the terminaL If the cursor is 
on the first position of this last line, then the editor is performing a computation, such as com¬ 
puting a new position in the file after a search or running a command to reformat part of the 
buffer. When this is happening you can stop the editor by sending an interrupt 

1.7. Getting oat of the editor 

After you have worked with this introduction for a while, and you wish to do something 
else, you can give the command ZZ to the editor. This will write the contents of the editor's 
buffer into the file you are editing, if you made any changes, and then quit from the edi¬ 
tor. You can also end an editor session by giving the command :qlCR;t this is a dangerous but 
occasionally x<wtiai command which ends the editor session and d iscar ds all your changes. 
You ne ed to know about this command in case you change the editor's copy of a file you wish 

* As we win see liter. * moves beck to tbs left Oik* control-* which is a backspace), j moves down (in the 
same column), k moves up (in the same column), and / moves to the Haiti. 

* On smart tetrainais where it is possible, the editor will quietly flajh the screen rather than rinfina the belL. 

* Bacfcspedsf over the 7* win also c a n c el the search. 

- On some systems, this murTuptibiUty comes si a price you cannot type ahead when the editor a commit- 
ins with the cursor on the bottom line. 

t All commands which read from (ha last display line on also be terminated with a asc as well as an ex. 
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only to look v. Be very careful not to jive this .command when you really want to save the 
changes you have made. 

2. Moving around in the file 

U. Scrolling and paging 

The editor has a number of commands for moving around in the file. The most useful of 
these is generated by hitting the control and D keys at the same time, a control-D or ‘*D\ W- 
will use this two character notation for referring to these control keys from now on. You may 
have a key labelled ’** on your terminal. This key will be represented as ‘f* in this document:. 
»*• ^ exclusively used as part of the ‘*x’ notation for control character s.? 

As you know now if you tried hitting *D. this command scrolls down in the file. The D 
thus stands for down. Many editor commands are mnemonic and this makes them much easier 
to remember. For instance the command to scroll up is ~U. Many dumb terminals can’t scroll 
up at ail* in which C3se hitting “U dears the screen and refreshes it with a line which is farmer 
hack in the file at the top. 

If you want to see more of the file bdow where you are. you can hit T to expose one 
more line at the bottom of the screen, leaving the cursor where it is. » The command *Y 
(which is hopelessly non-mnemonic, but next to “U on the keyboard) exposes one more line at 
the top of the screen. 

There are other ways to move around in the file; the keys T and *B t move forward and 
backward a page, keeping a couple of lines of continuity between screens so that it is possible to 
read through a file using these rather than *D and *TJ if you wish. 

Notice the difference between scrolling and paging. If you are trying to read the text in a 
file, hitting *7 to move forward a page will leave you only a little context to look back at. 
Scrolling on the other hand leaves more co n t ext, and happens more smoothly. You can con¬ 
tinue to read the text as scrolling is taking place. 

Searching, goto, and previous context 

Another way to position yourself in the file is by giving the editor a string to search for. 
Type the character / followed by a string of characters terminated by GL The editor will posi¬ 
tion the cursor at the next occurrence of this string. Try hitting a to then go to the next 
occurrence of this string. The chancer ? will search backwards from where- you are. and is 
otherwise like /.f 

If the search string you give the editor is not present in the file the editor will print a diag¬ 
nostic on the last line of the screen, and the cursor will be returned to its initial position. 

If you wish the search to match only at the beginning of a line, begin the search string 
with an t. To match only at the end of a line, end the search string with a I Thus /f searches 
will search for the word ’search’ at the beginning of a line, and /lastScs searches for the word 
’last' at the end of a line.* 


* If you don't have » *** key on your terminal then then is probably a k«y labelled T: in any ease these 
danocn are one end ihe same. 

» Version 3 only. 

t Not available in ail v 2 editors due to memoir constraints. 

♦ These searches will normally wrap around the end of the file, and thus find the join* even if it is not on a 
line in the direcnon you search provided it is anywhere else in the file. You can disable this wraparound in 
scans by jivinf the command at nownpscmOL or more briefly ae oewsex. 

•Actually, the strinj you jive to search for here can be a rtfuJar tx vr mo* in the sense of the editors erll) 
and «hl). If you don’t wish to, learn about this yet. you can disable this more jenerai faolity by doinj 
at nomagted: by pumnj this command in EONIT in your environment, you can have this always be in 
edea imore aoout EXlfffT later.) 
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The command C, when preceded by * number will position the cursor at Urn line in the 
hie. Thus 1G will move the cursor to the first line of the file. If you five G no count, then «i 
moves to the end of the file. 

If you are near the end of the file, and the last line is not at the bottom of the screen, the 
editor will place only the character on each remaining line. This indicates that the last* line 
in the file is on the screen; that is, the *** Unes are past the end of the file. 

You can find out the state of the file you are editing by typing a *G. The editor will show 
* you the name of the file you are editing, the number of the current line, the number of Unes in 
the buffer, and the percentage of the way through the buffer which you are. Try doing this 
now, and remember the number of the line you are on. Give a G command, to get to the end 
and then another G command to get bade where you were. 

You can also get bade to a previous position by using the command " (two back quotes). 
This is often more convenient than G because it requires no advance preparation. Try giving a 
G or a search with / or ? and then a w to get bade to where you were. If you accidentally hit n 
or any command which moves you far away from a context of interest, you can quickly get 
back by hitting ”. 

2J. Moving around on the screen 

Now try just moving the cursor around on the screen. If your terminal has arrow keys (4 
or 5 keys with arrows going in each direction) try them and convince yourself that they work. 
(On certain terminals using v2 editors, they won’t.) If you don’t have working arrow keys, you 
can always use h, J, k. and L Experienced users of W prefer these keys to arrow keys, because 
they are usually right underneath their fingers. 

Hit the 4* key. Each time you do, notice that the cursor advances to the next line in the 
file, at the first non-white position on the line. The — key is like + but goes the other w* j. 

These are very common keys for moving up and down lines in the file. Notice that if you 
go off the bottom or top with these keys then the screen will scroll down (and up if possible) to 
bring a line at a time into view. The return key has the same effect as the + key. 

Vi also has commands to take you to the top. middle and bottom of the screen. H will 
take you to the top (home) line on the screen. Try preceding it with a number as in 3H. This 
will take you to the third line on the screen. Many w commands take preceding numbers and 
do interesting things with them. Try M. which takes you to the middle line on the screen, and 
L. which takes you to the last line on the screen. L also takes counts, thus 51 will take you to 
the fifth line from the bottom. 

2.4. Moving within a line 

Now try picking a word on some line on the screen, not the first word on the line, move 
the cursor using return and — to be on the line where the word is. Try hiding the w key. 
This will advance the cursor to the next word on the line. Try hitting the b key to back up 
words in the line. Also try the ♦ key which advances you to the end of the current word rather 
than to the beginning of the next word. Also try S?ACS (the space bar) which moves right one 
—charamer and the BS (backspace or *H) key which moves left one character. The key h works 
as *H does and is useful if you don't have a BS key. (Also, as noted just above. 1 win move to 
the right.) 

If the line had punctuation in it you may have noticed that that the w and b keys stopped 
at each group of pu nct uation. You can also go back and forwards words without stopping at 
punctuation by using W and B rather than the lower case equivalents. Think of these as bigger 
words. Try these on a few lines with punctuation to see how they differ from the lower esse w 
and b. 

The word keys wrap around the end of line, rather than stopping at the end. Try moving 
to a word on a line below where you are by repeatedly hitting w. 




Z_5. Summon 
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advance the cursor one position 
badcwards to previous page 
scrolls down in the file 
exposes another lin» at the bottom (v3) 
forward to next page 
tell what is going on 
backspace the cursor 
next line, same column 
previous tine, same column 
scrolls up in the file 
exposes another line at the top (v3) 
next line, at the beginning 
previous line, at the be ginn ing 
cm for a following string forwards 
scan backwards 

haric a. word, ignoring punctuation 
go to specified line, last de fau lt 
home screen line 
middle screen line 
last screen line 

forward a word, ignoring punctuation 
back a word 
end of current word 
scan for next instance of / or ? pattern 
. word after this word 

2. $. View t 

If you want to use the editor to look at a file, rather than to make changes, invoke it as 
view instead of vi This will set the readonly option which will prevent you from accidently 
overwriting the file. 

3. Making* simple changes 
34* Inserting 

One of the most useful commands is the I (insert) command. After you type i. every¬ 
thing you type until you hit ESC is inserted into the file. Try this now, position yourself to 
some word in the file and try inserting text before this word. If you are on an dumb terminal it 
will for a minute, that some of the characters in your line have been overwritten, but 
they will reappear when you hit ESC 

Now try finding a word which can. but does not, end in an *s\ Position yourself at this 
word and type e (move to end of word), then a for append and then *SESC' to terminate the 
textual insert. This sequence of commands can be used to easily pluralixe a word. 

Try inserting and appending a few times to make sure you understand how this works: i 
placing text to the left of the cursor, a to the right. 

It is often the that you want to add new lines to the file you are editing, bet ore or 
after some specific line in the file. Find a line where this makes sense and then give the com¬ 
mand o to create a new line after the line you are on, or the command 0 to create a new line 
before the line you are on. After you create a new line in this way. text you type up to an ESC 

: Noi ivmiiabie in ill v 2 editors due to memory const raints. 
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is inserted on the new Use. 

Many related editor commands are invoked by the same letter key end differ only in that 
one is given by a lower case key and the other is given by an upper ease key. In these eases, 
the upper case key often differs from the lower case key in its sense of direction, with the 
upper case key working backward and/or up. while the lower ease key moves forward and/or 
down. 

Whenever you are typing is text, you can give many lines of input or just a few charac¬ 
ters. To type is more than one Use of text, hit a return at the middle of your input, a new 
line will be created for text, and you can continue to type. If you are on a slow and dumb ter¬ 
minal the editor may choose to wait to redraw the tail of the screen, and will let you type over 
the existing screes Uses. This avoids the lengthy delay which would occur If the editor 
attempted to keep the tail of the screen always up to date. The tail of the screen will be fixed 
up, and the missing lines will reappear, when you bit ESC 

While you are inserting new text, you-can use the characters you normally use at the sys¬ 
tem command level (usually *H or #) to backspace over the last character which you typed, 
and the character which you use to kill input Uses (usually <$, or *U) to erase the input 
you have typed on the current Use.t The character *W will erase t whole word and leave you 
after the space after the previous worth it is useful for quickly backing up in an insert. 

Notice that when you backspace during an insertion the characters you backspace over are 
not erased; the cursor moves backwards, and the characters remain on the display. This is 
often useful if you are planning to type is something similar. In any case the characters disap¬ 
pear when when you hit esc; if you want to get rid of them immediately, hit an esc and then a 
again. 

Notice also that you can't erase characters which you didn't insert, and that you can't 
backspace around the end of t line. If you need to back up to the previous line to make a 
correction, just hit ESC and move the cursor back to the previous line. After making the 
c o rrection you can return to where you were and use the insert or append command again. 

3-2. Making small corrections 

You can make small c o rrecnons in existing text quite easily. Find a single cbmacr 
which is wrong or just pick any character. Use the arrow keys to find the character, or get near 
the character with the word motion keys and then either backspace (hit the ss key or *H or 
even just h) or s?aCZ (using the space bar) until the cursor is on the character which is wrong. 
If the character is not needed then hit the x key, this deletes the character from the file. It is 
analogous to the way you x out characters when you make mistakes on a typewriter (except it’s 
not as messy). 

If the character is incorrect, you can replace it with the correct character by giving the 
command re, where c is replaced by the correct character. Finally if the character which is 
in co rre c t should be replaced by more than one character, give the command s which substitutes 
a string of c hara ca ra, ending with ESC. for it If there ire a small number of characters which 
are wrong you can precede s with a count of the number of characters to be replaced. Counts 
are also useful with x to specify the number of characters to be deleted. 

3.3. More corrections: operators 

You already know almost enough to make changes at a higher level. All you need to 
know now is that the d key acts as a delete operator. Try the command dw to delete a word. 
Try hitting . a few times. Notice that this repeats the effect of the dw. The command . repeats 
the last command which made a change. You can remember it by analogy with an ellipsis 


t la fact, the character *H (backspace) always works io ansa tbe last input character bare, retardless of what 
your true duraw is. 





Now try db. This deletes a word backwards, namely the preceding word. Try dSPACE. 
This deletes a single character, and is equivalent to the x command. 

Another very useful operator is c or change. The command cw thus changes the text of a 
sinale word. You follow it by the replacement text ending with an ESC. Find a word which you 
STdame to another, and try this now. Notice that the end of the text to be changed was 
marked with the character ‘S’ so that you can see this as you are typing in the new material. • 

3.4. Operating on lines 

it is often the you want to operate on lines. Find a line which you want to 

delete, and type dd. the d operator twice. This will delete the line. If you are on a dambus> 
annai the editor may just erase the line on the screen, replacing it with a line with only an <§ 
on iu This line does not correspond to any Une in your file, but only acts as a place holder. It 
helps to avoid a lengthy redraw of the rest of the screen which would be necessary to dose up 
the hole created by the deletion on a terminal without a delete line capability. 

Try repeating the c operator twice: this will change a whole line, erasing its previous con¬ 
tents and replacing them with text you type up to an ESC. t 

You can delete or change more than one line by preceding the dd or cs with a count. i.e. 
5dd deletes 5 lines. You can also give a command like dL to delete all the lines up to and 
induding the last line on the screen, or d3L to delete through the third from the bottom line. 
Try some commands like this now.' Notice that the editor lets you know when you change a 
large number of lines so that you can see the extent of the c h a ng e. The editor will also always 
tell you when a change you make affects text which you cannot see. 

3J. Undoing 

Now suppose that the' last change which you made was incorrect; you could use the insert; 
delete and append commands to put the correct material back. However, since it is often e 
case that we regret a change or make a change incorrectly, the editor provides a a (undo) com¬ 
mand to reverse the last change which you made. Try this a few times, and give it twice in a 
row to notice that an u also undoes a u. 

The undo command lets you reverse only a single change. After you make a number of 
changes to a line, you may deride that you would rather have the original state of the Une back. 
The U command restores the current line to the state before you started changing it. 

You can recover text which you delete, even if undo will not bring it bade see the section 
on recovering lost text below. 


3.6. Summary 

SPaCS 
“H 
~W 
erase- 
kill 
• 

o 
u 

a 
e 

t Th* command S is * convenient synonym for for 

lin n L while s 'd a substitute on dancers. . , . _ 

• One subtle sous here involves uimt the / jeareh after a 1 This win normally Cele» cSaracers from the 
e^n pSuoTS thTpota of the match. If what is Cessed is to delete whole lines mdudtn, the two potnu. 
pve the pattern as /pei/+il. a line address. 


advance the cursor one position 

backspace the cursor 

erase a word during as insert 

your erase (usually *H or £), erases a character during an insert 

your kill (usually ©. ‘X. or *TJ), kills the insert on this line 

repeats the changing co mm a n d 

opens and inputs new lines, above the current 

undoes the changes you made to the current line 

appends text after the cursor 

changes the object you specify to the following text 

by analogy with a. Think of 5 aa a jubsuuu* on 
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d 


o 

a 


deletes the object you specify 

inserts text before the cursor 

opens end inputs new lines, below the current 

undoes the lest change 


4. Moving about; rearranging and duplicating text 
4.1. Low lrrel character motions 

Now move the cursor to a line where there is a punctuation or a bracketing character such 
as a parenthesis or a comma or period. Try the command lx where x is this character. This 
command finds the next x danevu to the right of the cursor in the current line. Try then hit* 
ting a which finds the next instance of the same character. By using the f command and then 
a sequence of ;'s you can often get to a particular place in a line much faster than with a 
sequence of word motions or SPACES. There is also a F command, which is like f. but searches 
backward. The ; command repeats F also. 

When you are operating on the text in a line it is often desirable to deal with the charac- 
ten up to. but not mgfarfing , the first instance of a character. Try dlx for some x now and 
notice that the x danger is deleted. Undo this with a and then try dtx the t here stands for 
to. Le. delete up to the next x. but not the x The command T is the reverse of l 

When working with the text of a single line, an I moves the cursor to the first non-white 
position on the line, and a S moves it to the end of the line. Thus Sa will append new text at 
the end of the current line. 

Your file may have tab Cl) characters in it These characters are represented as a number 
of spaces expanding to a tab stop, where tab stops are every 8 positions.* When the cursor is at 
a tab. it sits on the last of the several spaces which represent that tab. Try moving the cursor 

and forth over tabs so you understand how this works. 

On rare your file may have nonprinting characters in it These characters are 

displayed in the same way they are r epr es ented in this document, that is with a two character 
code, the first da nger of which is On the screen non-printing cha r a ct e r s resemble a 
danger adjacent to another, but spacing or backspacing over the ch a r ac t e r will reveal that the 
two characters are. like the spaces representing a tab c h a ra c ter , a single cha ra c t er. 

The editor sometimes discards control characters, depending on the character and the set¬ 
ting of the beautify option, if you attempt to insert them in your file.. You can get a control 
danger in the file by beginning an insert and then typing a *V before the control character. 
The *Y quotes the following character, causing it to be inserted directly into the file. 

4.2. Higher level text objects 

In working with a document it is often advantageous to work in terms of sentences, para¬ 
graphs, and sections. The operations ( and ) move to the begi nn in g of the previous and next 
respectively. Thus the command d) will delete the rest of the current sentence: like¬ 
wise d( will delete the previous sentence if you are at the be ginnin g of the current sentence, or 
the current scm ence up to where you are if you are not at the be ginnin g of the current sen- 

to ne ? 

A is defined to end at a *.\ *!* or *?* which is foUowed by either the end of a 

line, or by two spaces. Any number of dosing *)*. ‘1*. *"* and ,M characters may appear after 
the *.*. *!’ or *?’ before the spaces or end of line. 

The operations ( and ) move over paragraphs and the operations II and II move over sec- 
tions.f 

• This is settable by s com ma nd of the form se a*JCL where x is * to set tabstops every four columns. 

This has effect on the scre en representation within the editor. 

t Tbe il and II operations require the operation character to be doubled because they can move the cursor far 
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A paragraph begins after each empty line, and also at each of a set of paragraph macros, 
specified by the pairs of characters in the definition of the string valued option paragraphs. The 
default setting for this option defines the paragraph macros of the -ms and -mm macro pack* 
ages. i.e. the MP\ ‘X?’. \PP* and *.QP\ \P’ and ‘JLT macros.* Each paragraph boundary is 
also a "sentence boundary. The sentence and paragraph commands can be given counts to 
operate over groups of sentences and paragraphs. 

Sections in the editor begin after each macro in the stations option, normally ‘.NH*. ‘.SH\ 
•XT and * JJU\ and each line with a formfeed t, in the first column. Section boundaries are 
always line and paragraph bou n da r ies also. 

Try experimenting with the sentence and paragraph commands until you are sure how 
they work. If you have a large document, try too king through it using the secion commands. 
Toe secaon commands interpret a preceding count as a different window size in which to 
redraw the screen at the new location, and this window size is the base size for newly drawn 
windows uadi another size is specified. This is very useful If you are on a slow terminal and 
are looking for a particular section. You can give the first section command a small count to 
then see — successive section headi n g in a s m all window. 

4JJ. Rearranging and duplicating text 

The editor has a single unnamed buffer where the. last deleted or changed away text is 
saved, and a set of named buffers a-z which you can use to save copies of text and to move 
text around in your file and between files. 

The operator y yanks a copy of the object which follows into the u nn a m ed buffer. If pre* 
by a buffer name, ‘xg, where x here is replaced by a letter a—s. it places the text in the 
named buffer. The text can then be put back in the file with the commands p and P: p puts 
me text after or below the cursor, while P puts the text before or above the cursor. 

If the text which you yank forms a part of a line, or is an object such as a sentence which 
partially spans more than one line, then when you put the text back, it will be placed after the 
cursor (or before if you use P). If the yanked text forms whole lines, they will be put back as 
whole lines, without changing the current line. In this case, the put aca much like a o or O 
command. 

Try the c ommand YP. This makes a copy of the current line and leaves you on this copy, 
which is pta cr* before the current line. The command Y is a convenient abbreviation for yv. 
The command Yp will also make a copy of the current line, and place it after the current line. 
You can give Y a count of lines to yank, and thus duplicate several lines: try 3YP. 

To move text within the buffer, you need to delete it in one place, and put it back in 
another. You can precede a delete operation by the name of a buffer in which the text is to be 
stored as in *a5dd deleting 5 lines into the named buffer a. You can then move the cursor to 
the eventual resting place of the these lines and do a *ap or *aP to put them back. In fao. you 
can switch and edit another file before you put the lines back, by giving a command of the form 
a nameCk where namt is the name of the other file you want to edit. You will have to write 
back the contents of the current editor buffer (or discard them) if you have made changes 
before the editor will let you switch to the other file. An ordinary delete command saves the 
text in the unnamed buffer, so that an ordinary put can move it elsewhere. However, the 
unnamed buffer is lost when you change files, so to move text from one file to another you 
should use an unnamed buffer. 


from where it currently is. While it is easy to set tack with the commend ". these commands would still ta 
frustrating if they *er* easy u> hit a c cide n tally. 

i You can easily change or extend this set of macros by issgninf t different string to the paramo** option 
in your EXINTT. See section 6.2 for details. The \bp* directive is also considered to start a paraeraoh. 
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4.4. Summary. 


$ 

) 


u 


II 

fcc 

P 


tx 

Fx 

P 

Tx 


r 


first non-white on line 
end of line 
forward sentence 
forward paragraph 
forward section 
backward sentence 
backward paragraph 
backward section 
find x forward in line 

put text back, after cursor or below current line 
yank operator, for copies and moves 
up to x forward, for operators 
f backward in line 

put text before cursor or above current line 
t backward in line 


5. High level commands 

5.1. Writing, quitting, editing new files 

So far we have seen how to enter w and to write out our file using either ZZ or rwCR. 
The first exits from the editor, (writing if changes were made), the second writes and stays in 
the editor. 

If you have changed.the editor’s copy of the file but do not wish to save your changes, 
either because you messed up the file or decided that the changes are not an improvement to 
the file, then you can give the command tq.'CR to quit from the editor without writing the 
changes. You can also reedit the same file (starting over) by giving the command :*!ol These 
commands should be used only rarely, and with caution, as it is not possible to recover the 
you have tussle after you discard them in this m a n ner. 

You can edit a different file without leaving the editor by giving the command :e nameCR. 
If you have not written out your file before you try to do this, then the editor will tell you this, 
and delay editing the other file. You can then give the command rwCR to save your work and 
then the :e nameCR command again, or carefully give the command al narr.sCR. which edits 
the other file discarding the changes you have made to the current file. To have the editor 
automatically save changes, include set autowrite in your EXINTT, and use m ins t ead of te. 

5-2. Escaping to a shell 

You can get to a shell to execute a single command by giving a w command of the form 
? landca The system will run the single command and and when the co mm a n d ani s h cs. the 
editor will ask you to hit a RETURN to continue. When you have finished looking at the output 
on the screen, you sh ould hit RETURN and the editor will dear the screen and redraw it. You 
can then continue editing. You can also give another : command when it asks you for a 
RETURN; in this case the screen will not be redrawn. 

If you wish to execute more than one command in the shell, then you can give the com¬ 
mand tshCR. This will give you a new shell, and when you finish with the shell, ending it by 
typing a *D, the editor will dear the screen and continue. 

On systems which support it, *Z will suspend the editor and return to the (top level) 
shell When the editor is resumed, the screen will be redrawn. 
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5 J. Marking and returning 

The command " returned to the previous place after a motion of the cursor by a com¬ 
mand such as /. ? or G. You can also mark lines in the file with single letter tags and return to 
these marks later by naming the tags. Try marking the current line with the command nu. 
where you should pick some letter for x, say ‘a’. Then move the cursor to a different line (any 
way you like) and hit 'a. The cursor will return to the place which you marked. Marks last 
only until you edit another file. 

When using operators such as d and referring to marked lines, it is often desirable to 
delete whole lines rather than deleting to the exact position in the line marked by m. In this 
case you can use the form ‘x rather than *x Used without an operator, 'x will, move to the first 
non-white character of the marked line: similarly ~ moves to the first non-white character of 
the line containing the previous context mark **. 

5.4. Adjusting the screen 

If the screen image is messed up because of a transmission error to your terminal, or 
because some p rog r am other than the editor wrote output to your terminal, you can hit a *L. 
the ascii form-feed character, to cause the screen to be refreshed. 

On a tfarnh terminal, if there are <3 lines in the middle of the screen as a result of line 
deletion, you may get rid of these lines by typing *H to cause the editor to retype the screen, 
closing up these holes. 

Finally, if you wish to piace a certain line on the screen at the top middle or bottom of ' 
the screen, you can position the cursor to that tine, and then give a z command. You should 
follow the z command with a return if you want the line to appear at the top of the window, a 
. if you want it at the center, or a — if you want it at the bottom, (z.. z-, and z+ are not avail¬ 
able on all v2 editors.) 

6. Special topics 

6.2. Editing on slow terminals 

When you are on a slow terminal, it is important to limit the amount of output which is 
jeacmed to your screen so that you will not suffer long delays, waiting for the screen to be 
refreshed. We have already pointed out how the editor optimizes the updating of the screen 
during insertions on dumb terminals to limit the delays, and how the editor erases lines to <§ 
when they are deleted on dumb terminals. 

The use of the slow terminal insertion mode is controlled by the slowoptrr option. You 
can force the- editor to use this mode even on faster terminals by giving the command :se 
slowCR. If your system is sluggish this helps lessen the amount of output coming to your ter¬ 
minal. You can disable this option by :s« noslowCR. 

The editor can simulate an intelligent terminal on a dumb one. Try giving the command 
:se redrawCR. This simulation generates a great deal of output and is generally tolerable only 
on lightly loaded systems and fast terminals. You can disable this by giving the command 
ae noredrawCR. 

The editor also makes editing more pleasant at low speed by starring editing in a small 
window, and letting the window expand as you edit. This works particularly well on intelligent 
terminals. The editor can expand the window easily when you insert in the middle of the 
screen on these terminals. If possible, try the editor on an intelligent terminal to see how this 
works. 

You can control the size of the window which is redrawn each time the screen is cleared 
by giving window sizes as argument to the commands which cause large screen motions: 

: / ? II II ‘ ' 

Thus if you are searching for a particular instance of a common string in a file you can precede 
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the first search command by a small number, say 3, and the editor will draw three line windows 
around e«eh instants of the string which it locates. 

You can easily expand or contract the window, placing the current line as you choose, by 
giving a number on a z command, after the z and before the following RETURN, . or Thus 
the command zfi. redraws the screen with the current line in the center of a five line window.! 

If the editor is redrawing or otherwise updating large portions of the display, you can 
interrupt this updating by hitting a DEL or RUB as usual. If you do this you may partially con¬ 
fuse the editor about what is displayed on the screen. You can still edit the text on the screen 
if you wish; dear up the confusion by hitting a *L: or move or search again, ignoring the 
current state of the display. 

See section 7.8 on open mode for another way to use the w command set on slow termi¬ 
nals. 

6.2. Options, set, and editor startup files 

The editor has a set of options, some of which have been mentioned above. The most 
useful options are given in the following table. 


Name Default 


autoindent 

noai 

autowrite 

noaw 

ignorecase 

noic 

lisp 

noiisp 

list 

nolist 

magic 

nomagic 

number 

nonu 

paragraphs 

para-tPLPPPQPbpP U 

redraw 

nore 

sections 

sect-NHSHH HU 

shiftwidth 

sw-8 # 

showmatch 

qrtcffl 

siowopen 

slow 

term 

dumb 


Description 

Supply indentation automatically 

Automatic write before a, na. *1,! 

Ignore case in searching 
(()) commands deal with S-expressions 
Tabs print as T; end of lines marked with S 
The characters. [ and " are special in scans 
Lines are displayed prefixed with line numbers 
Macro names which start paragraphs 
Simulate a smart terminal on a dumb one 
Macro names which start new sections 
Shift distance for <. > and input *D and *T 
Show matching ( or ( as ) or) is typed 
Postpone display updates during inserts 
The kind of terminal you are using. 


i 


The options are of three kinds: numeric options, string options, and toggle options. You 
mw set numeric and string options by a statement of the form 

set opr—vai 

and toggle options can be set or unset by statements of one of the forms 

set opt 
set so opt 

These statements can be placed in your EXINTT in your environment, or given while you are 
running v> by preceding them with a : and following them with a CL 

You can get a list of all options which you have changed by the command tsetCR. or the 
value of a single option by the command set opr?CR. A list of all possible options and their 
values is generated by set allCR. Set can be abbreviated se. Multiple options can be placed on 
one line, e.g. tse ai aw nuCL 

Options set by the set command only last while you stay in the editor. It is common co 
want to have certain options set whenever you use the editor. This can be accomplished by 
creating a list of ex commands! which are to be run every time you start up ex. edit . or w. A 


♦ y<oie that the command 5x. has an entirety different effect, piaonf line J in the center of a new window, 
t All commands which start with : art ex com mand s 
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typical list indudes a set command, and possibly a few map commands (on v3 editors). Sine: 
it is advisable to get these commands on one line, they can be separated .with the | character, for 
example: 

set ai aw tersepnap © ddimap # x 

which sets the options autoindent, autownte, terse, (the set command), makes © delete a tine, 
(the first map), and makes # delete a character, (the second map). (See section 6.9 for a 
description of the map command, which only works in version 3.) This string should be plated 
in the variable EXINTT in your environment. If you use ah, put this line in the file .login in 
your home directory: 

setenv EXINTT 'set ai aw tersemap © ddimap JP x' 

If you use the standard v? shell, put these lines in the file .profile in your home diremory: 

EXTNI7—'set ai aw tersemap © ddimap rr x' 
export EXINTT 

On a version 6 system, the concept of environments is not present. In this case, put the line in. 
the file .exrc in your home directory. 

set ai aw tersemap © ddjmap # x 

Of course, the particulars of the line would depend on which options you wanted to set. 

6_3. Recovering lost lines 

You might have a serious problem if you delete a number of lines and then regret that 
they were deleted. Despair not, the editor saves the last 9 deleted blocks of text in a set of 
numbered registers 1 —9. You can. get the n’th previous deleted text back in your file by the 
command m n p. The ' here says that a buffer name is to foilow, n is the number of the buffer 
you wish to try (use the number 1 for now), and p is the put command, which puts text in the 
buffer after the cursor. If this doesn’t bring back the text you wanted, hit u to undo this and 
then . (period) to repeat the put command. In general the . command will repeat the last 
change you made. As a special case, when the last command refers to a numbered text buffer, 
the . command increments the number of the buffer before repeating the command. Thus a 
sequence of the form 

"lpu-a-u. 

will, if repeated long enough, show you all the deleted text which has been saved for you. You 
can omit the a commands here to gather up ail this text in the buffer, or stop after any . com¬ 
mand to keep just the then recovered text. The command P can also be used rather than p to 
put the recovered text before rather than after the cursor. 

6.4. Recovering lost files 

If the system crashes, you can recover the work you were doing to within a few changes. 
You will normally receive mail when you next login giving you the name of the file which has 
been saved for you. You should then change to the directory where you were when the system 
crashed and give a command of the form: 

% vi —r name 

replacing name with the name of the file which you were editing. This will recover your work 
to a point near where you left off.t 

* In rare cues, some of the lines of the file mar he lost. The editor will jive you the numhets of these lines 
and the text of the lines will be replaced by (he siring ‘LOST. These lines will almost always' be among the 
last few which you changed. You can either choose to discard the changes which you made fif they are easy 
to remake) or to replace the few lost lines by hand. 
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You can get a listing of the files which are saved for you by giving the command: 

% rt -r 

If there is more than one instance of a particular file saved, the editor gives you the newest 
instance each time you recover it. You can thus get an older saved copy back by first recover¬ 
ing the newer copies. 

For this feature to work, w must be correctly installed by a super user on your system, 
and the mail progr a m must exist to receive mail The invocation “W S’ will not always list ail 
saved files, but they can be recovered even if they are not listed. 

(J. Continuous text Input 

When you are typing in large amounts of text it is convenient to have lines broken near 
the right margin automatically. You can cause this to happen by giving the command :se 
wm—lOat. This causes all lines to be broken at a space at least 10 columns from the right 
hand edge of the sc re en .* 

If the editor breaks an input line and you wish to put it back together you can tell it to 
join the lines with J. You can give J a count of the number of lines to be joined is in 3J to 
join 3 lines. The editor supplies white space, if appropriate, at the juncture of the joined lines, 
and leaves the cursor at this white space. You can kill the white space with x if you don’t want 
it 

6.6. Features for editing programs 

The editor has a number of commands for editing programs. The thing that most distin¬ 
guishes editing of programs from editing ef text is the desirability of maintaining an indented 
structure to the body of the progr a m. The editor has a auiomdem facility for helping you gen¬ 
erate correctly indented programs. 

To enable this facility you can give the command sc aid. Now try opening a new line 
with o and type some characters on the line after a few tabs. If you now start another line, 
notice that the editor supplies white space at the beginning of the line to line it up with the pre¬ 
vious line. You cannot backspace over this 'indentation, but you can use T) key to backtab 
over the supplied indentation. 

Each time you type *D you back up one position, normally to an S column boundary. 
This amount is settable; the editor has an option called shifiwidth which you can set to change 
this value. Try giving the command sm sw*4cr and then experimenting with autoindem 
again. 

For shifting lines in the pro g ram left and right, there are operators < and >. These shift 
the lines you specify right or left by one sJti/Mdth. Try < < and > > which shift one line left 
or right, and <L and >L shifting the rest of the display left and right 

If you have a complicated expression and wish to see bow the parentheses match, put the 
cursor at a left or right parenthesis and hit tt. This will show you the matching parenthesis. 
This works also for braces { and ), and brackets [ and ]. 

If you are editing C programs, you can use the II and II keys to advance or retreat to a 
line starting with a (, Le. a function declaration at a time. When II is used with an operator it 
stops after a line which starts with ); this is sometimes useful with yll. 


* This fawn is not available on tom* v2 editors. In «2 editors when it is available, the break «an only oc¬ 
cur to the rifht of the specified boundary instead of to the left 





(.7. Filtering portions o t tbs buffer 

You can run system commands over portions of the buffer using the operator!. You can 
use this to sort lines in the buffer, or to reformat portions of the buffer with a pretty-printer. 
Try typing in a list of random words, one per line and ending them with, a blank line. Back up 
to the beginning of the list, and then give the command JjsortCR. This says to sort the next 
paragraph of material, and the blank line ends a paragraph. 

W. Commands for editing LISPt 

If you are editing a us? program you should set the option lisp by doing :* iispct. This 
changes the ( and ) commands to move backward and forward over s-expressions. The { and) 
commands are like (and ) but don't stop at atoms. These can be used to skip to the next list, 
or through a comment quickly. 

The autotndenr option works differently for US?, supplying indent to align at the first argu¬ 
ment to the last open list. If there \s no such argument then the indent is two spaces more 
than the last level. 

There is another option which is useful for typing in us?. the showmatdt option. Try set¬ 
ting it with se smot and then uy typing e T some words and then a *)’. Notice that the cur¬ 
sor shows the position of the T which matches the T briefly. This happens only if the match- 
ing *(’ is on the screen, and the cursor stays there for at most one second. 

The editor also has an operator to realign existing lines as. though they bad been typed in 
with top and autointUnt set. This is the - operator. Try the command at the beginning of 
a function. This will realign all the lines of the function declaration. 

When you are editing US?„ the (I and I] advance and retreat to lines beginning with a (. 
and are useful for dealing with entire function definitions. 

6.3. Macros* 

^ has a parameter! ess macro facility, which lets you set it up so that when you bit a single 
keystroke, the editor will am as though you had hit some longer sequence of keys. You can set 
this up if you find yourself typing the same sequence of commands repeatedly. 

Briefly, there are two flavors of macros: 

a) Ones where you put the macro body in a buffer register, say x You can then type <&x to 
invoke the macro. The @ may be followed by another 9 to repeat the last macro. 

b) You can use the map command from v» (typically in your EXJNTD with a command of the 
form: 

osap IksrhszK 

mapping Iks into rhs. There are restrictions: (to should be one keystroke (either 1 charac¬ 
ter or one function key) since it must, be entered within one second (unless notimeout is 
set, in which case you can type it as slowly as you wish, and w will wait for you to finish it 
before it echoes anything). The (to can be no longer than 10 characters, the ms so longer 
than 100. To get a space, tab or newline into (to or rto you should escape them with a *V. 
(It may be necessa r y to double the *Y if the map command is given insid e w. rather 
in ccj Spaces and tabs inside the rhs need not be escaped. 

Thus to make the q key write and exit the editor, you can give the command 
map q rwq*Wat at 

which means that whenever you type q, it will be as though you had typed the four characters 
rwqca. A *V’s is needed because without it the Gt would end the : command, rather than 


f The usf features are not ivaiUhie on some v2 editors due to manor? constraints. 
: The macro feature a available only m version J editors. 
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becoming pen of the map definition. There ere two “T» because from within n. two *V’s must 
be typed to get one. The first CX is pert of the rhs, the second terminates the : command. 

Macros can be deleted with ' 

yurwmp lhS 

If the Ihs of a macro is **#0” through **#9’\ this maps'the particular fu nct ion key instead 
of the 2 ’*#” sequence. So that terminals without function keys can access such 

definitions, the form **#x” will mean function key x on all ter min a ls (and need not be typed 
within one second.) The character "#” can be changed by using a macro in the usual war 

anap-m# 

to use ub, for example. (This won’t affect the map command, which still uses #, but just the 
invocation from visual mo de. 

The undo command reverses an entire macro call as a unit, if it made any changes. 

Placing a *!* after the word map causes the mapping to apply to input mode, rather than 
command mode. Thus, to arrange for *T to be the same as 4 spaces in input mode, you can 
type: 

snap *T *YWbb 

where V is a blank. The “V is necessary to prevent the blanks from being taken as white space 
between the Ihs and Mi 

7. Word Abbreviations tt 

A feature to macros in input mode is word abbreviation. This allows you to type a 

short word and have It expanded into a longer word or words. The commands are abbreviate 
and mnabbrrriatfr (tab and ana) and have the same syntax as snap. For example: 

ab eecs Engineering and Computer Sc ienc es 

the wort ‘eecs’ to always be changed into the phrase ‘Eectrical Engineering and Com¬ 
puter Sciences’. Word abbreviation is different from macros in that only whole worts are 
affected. If ‘eecs’ were typed as pert of a larger wort, it would be left alone. Also, the partial 
word is echoed as it is typed. There is no need for an abbreviation to be a single keystroke, as 
it should be with a macro. 

7.1. Abbreviations 

The editor has a. number of short commands which abbreviate longer commands which we 
have i ntrodu ced here. You can find these commands easily on the quick reference card. They 
often save a bit of typing and you can learn them as conveni ent . 

8. Nitty-gritty details 

8.1. Line representation In the display 

The editor folds long logical lines onto many physical lines in the display. Commands 
which advance lines advance logical lines and will skip over all the segments of a line in one 
motion. The command | moves the cursor to t specific column, and may be useful for gening 
near the middle of a long line to split it in half. Tty 80| on a line which is more than 30 
columns !ong.t 

The editor only puts full lines on the display; if there is not enough room on the display 
to fit a logical line, the editor leaves the physical line empty, placing only an @ on the line as a 


n Version 3 only. 

t You on make Iona lines ««ry easily by usm* i to join tofetber short fines. 
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place bolder. When you delete lines on a dumb terminal, the editor will often just clear the 
lines to <3 to save time (rather than rewriting the rest of the screen.) You can always maximize 
the information on the screen by jiving the "R command. 

If you wish, you can have the editor place line numbers before each line on the dispiay. 
Give the command :se nucit to enable this, and the command :s« nonuca to turn it off. You 
can have tabs represented as *1 and the ends of lines.indicated with ‘S’ by giving the command 
3 * Ustou 3« oolistQt turns this off. 

Finally, li nes consisting of only the c h aracte r *** are displayed when the last line in the file 
is in the middle of the screen. These represent physical lines which are past the logical end of 
file. 

S>2. Counts 

Most v» commands will use a preceding count to affect their behavior in some way. The 
following table gives the common ways in which the counts are used: 


new window size 
scroll amount 
line/column number 
repeat effect 


: / ? II 11 * ' 
*13 *TJ 
i G | 

most of the rest 


The editor «s«imaira a notion of the current default window size. On terminals which run 
at speeds greater than 1200 baud the editor uses the full terminal screen. On terminals which 
are slower than 1200 baud (most dialup lines are in this group) the editor uses S lines as the 
default window size. At 1200 baud the d ef a u lt is 16 Uses. 

This size is the size used when the editor deara and refills the screen after a search or 
other motion moves far from the edge of the current window. The co mm a n ds which take a 
new window size as count all often cause the screen to be redrawn. If you anticipate this, but 
do not need as large a window as you are currently using, you may wish to change the screen 
citi» by specifying the new size before these com man d s . In any case, the number of lines used 
on the sc r een will expand if you move off the top with a — or similar command or off the bot¬ 
tom with a command such as RETURN or *D. The window will revert to the last specified size 
the next time it is cleared and refilled, t 

The scroll commands *D and ~U likewise rem em b e r the amount of scroll last specified, 
using half the basic window size initially. The simple insert commands use a count to sc ecu y a 

repetition of the inserted text. Thus 10a+-SC will insert a grid-like string of text. A 

tYw commands also use a preceding count as a line or column number. 

Except for a few commands which ignore any counts (such as *10, the rest of the editor 
commands use a count to indicate a simple repetition of their effect. Thus 5w advances five 
words on the current line, while 5RETURN advances five lines. A very useful instance of a 
count as a repetition is a count given to the . command, which repeats the last changing com¬ 
mand. If you do dw and then 3., you will delete first one and then three words. You can then 
delete two more words with 2.. 


8J. More file manipulation commands 

The following table lists the file manipulation commands which you can use when you are 
in w. Ail of these commands are followed by a CR or ESC The most basic commands are :w 
and A normal editing session on a single file will end with a ZZ command. If you are edit¬ 
ing for a long period of time you can give rw commands occasionally after major amounts or 
editing, and then finish with a ZZ. When you edit more than one file, you can finish with one 


T 3ut not by a ~L wmcb just redraws ibe seen as it is. 
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nr 

write back changes 

nrq 

write and quit 

a 

write (if necessary) and quit (same as ZZ). 

a name 

edit file name 

a! 

reedit, discarding changes 

:• + nome 

edit, starting at end 

a +it 

edit, starting at line n 

a # 

edit alternate file 

nr name 

write file namt 

nr! name 

overwrite file name 

'jaym name 

write lines x through / to name 

7 name 

reed file name into buffer 

7 ! and 

reed output of emdinto buffer 

a 

edit next file in argument list 

a! 

edit next file, discarding changes to current 

a arts 

specify new argument list 

rta tat 

edit file containing tag tog, at teg 


with a nr and start editing a new file by giving a a command, or set autowhu and use :a 
<file>. 

If you make changes to the editor's copy of a file, but do not wish to write them back, 
•then you must give an ! after the command you would otherwise use: this forces the editor to 
discard any changes you have made. Use this carefully. 

The a- command can be given a + argument to start at the end of the file, or a +/r argu¬ 
ment to start at line n. In acuality, n may be any editor command not containing a space, use¬ 
fully a scan like +/pat or +?po& In forming new names to the • command, you can use the 
character % which is replaced by the current file name, or the character # which is replaced by 
the alternate file name. The alternate file name is generally the last name you typed other than 
the current file. Thus if you try to do a » and get a diagnostic that you haven’t written the file, 
you can give a nr command and then a » # command to redo the previous ta. 

You can write pan of the buffer to a file by finding out the lines that bound the range to 
be written using *G, and giving these numbers after the : and before the w. separated by ,’s. 
You can also mark these lines with a and then use an address of the form '*> on the w com¬ 
mand here. 

You can read another file into the buffer after the current line by using the 7 command. 
You can similarly read in the output from a command, just use land instead of a file name. 

If you wish to edit a set of files in succ ess io n, you can give all the names on the command 
line, and then edit each one in turn using the command a. It is also possible to respecify the 
list of files to be edited by giving the a command a list of file names, or a pattern to be 
expanded as you would have given it on the initial *> command. 

If you an editing large programs, you win find the da command very useful. It utilizes a 
data base of funcuon names and their locations, which can be created by p rogr a ms such as 
aags. to quickly find a function whose name you give. If the da command win requin the edi¬ 
tor to switch files, then you must nr or abandon any changes before switching. You can repeat 
the da command without any arguments to look for the same tag again. (The tag featun is not 
available in some v2 editors.) 

8.4. Mon about searching for strings 

When you an searching for strings in the file with / and ?, the editor normally places you 
at the next or previous occ ur r en ce of the string. If you an using an operator such as d. c or y. 
then you may well wish to affect lines up to the line before the line containing the pattern. 
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You an give * search of the form /pat/—* to r«ftr to the *'th lino before the next line con- 
uminx«A or you an use + insteed of - to refer to the lines after the one conumm* pat. If 
you*dot^ftv* aUne offset, then the editor will affect characters up to the match place, rather 
t h«w whole lines; thus use "+0” to affect to the line which matches. 

You can have the editor itnore the case of words in the searches it does by Jiving the 
command ae kOL The command a* nolcCX turns this off. 

Stxinp liven to searches may actuaUy be muier expressions. If you do not want or need 
this facility, you should 


set nomxgic 


in your DGNTT. In this case, only the characters f and S ire special in patterns. The characer 
\ is also then s pedal (is it is most everywhere in the system), and may be used to get at the an 
extended pattern matching facility. It is also necessary to use a \ before a / m a forward man 
orT? to ebedeward scan, to any ose. The following table fives the extended forms when 

magic is set. 


? 

S 

• 

\< 

\> 

t*H 

tx-vi 


at beginning of patters, matches beginning of line 
at end of pattern, matches end of line 
matches any chancier 
matches the beginning of a word 
the end of a word 
matches any stogie character to nr 
matches any single cbancur not to str 
matches any character between x and / 

jay number of the pre ce d ing pa tter n 


If you use nomagic mode, then the . I and • primitives are given with a preceding V 
SJ. More about Input mode 

There are a number of characters which you can use to make corrections during input 
mode. There are summarized to the following table. 

*H deletes the last input character 

~W deletes the last input word, defined as by b 

erase your erase character, same as *H 
kill your kill character, deletes the input on this line 
\ gap ** a following *H and your erase and kill 
tsc ends an insertion 

on. interrupts an insertion, terminating it abnormally 

Gt sorts a new line 

D backtabs over autoindent 

0*D kills ail the autoindenx 

I'D 5 am* as QD. but restores indent next line 

*Y qtj nT? the next non-printing character into the file 


Th» most usual way of making co rrecaons to input is by typing *H to correct a single 
charaaer. or by typing one or more ~W’s to back over incorrect words. If you use $ as your 
erase character to the normal syste m , it will work like ”H. 

Your system kill character, normally O. D or *TJ. will erase all the input you have given 
on the current line. In general, you on neither erase input back around a line boundary nor 
can you erase characters which you did not insert with this insertion command. To maKe 
corrections on the previous line after a new line has been started you can hit ESC to end the 
insertion, move over and make the correcaon. and then return to where you were to continue; 
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The command A which appends at the end of the current line is often useful for continuing. 

If you wish to type in your erase or kill character (say # or <S) then you must precede it 
with a \, just as you would do at the normal system command level. A more general way of 
typing non-priming characters into the file is to pr e cede them with a *V. The *Y echoes as a f 
character on which the cursor rests. This indicates that the editor expects you to type a control 
character. In fact you may type any character and it will be inserted into the file at that point.' 

If you are using autoindint you can backtab ever the indent which it supplies by typing a 
~D. This backs up to a shifiwidth boundary. This only works immediately after the supplied 
autoindent. 

When you are using autoindtnt you may wish to place a label at the left margin of a line. 
The way to do this easily is to type f and then *D. The editor will move the cursor to the left 
margin for one line, and restore the previous indent on the next. You on also type a 0 fol¬ 
lowed immediately by a D if you wish to kill all the indent and not have it come back on the 
next line. 

5.6. Upper case only terminals 

If your terminal has only upper case, you can still use w by using the normal system con¬ 
vention for typing on such a terminal. Characters which you normally type are convened to 
lower case, and you can type upper case letters by preceding them with a V The chances { * } 

|' are not available on such terminals, but you can escape them as \( \f \) \! Y. These charac¬ 
ters are represented on the display in the same way they are typed.* a 

8.7. VI and ex 

Yi is actually one mode of editing within the editor ex. When yon are running w you can 
escape to the tine oriented editor of ex by giving the co mm and Q. All of the : commands 
which were introduced above are available in ex. Likewise, most er commands can be invoked 
from w using u Just give them without the : and follow them with aOL 

In rare an internal error may occur in W. In this ease you will get a d iagn ostic 

and be left in the command mode of ex. You can then save your work and quit if you wish by 
giving a c ornTnand x after the : which er prompts you with, or you can reenter w by giving era 
w command. 

There are a number of things which you can do more easily in ex than in nr. Systematic 
in line oriented material are particularly easy. You can read the advanced editing docu¬ 
ments for the editor ed to find out a lot more about this style of editing. Experienced users 
often mix their use of er command mode and w command mode to speed the work they are 
doing. 

O. Open mode: vi on hardcopy terminals and ‘‘glass tty's” * 

If you are on a hardcopy terminal or a terminal which does not have a cursor which can 
move off the bottom tine, you can sell use the command set of w, but in a different mode. 
When you give a W command, the editor wQl tell you that it is using open mode. This name 
comes from the open command in ex which is used to get into the same mode. 

The only difference between ‘visual mode and open mode is the way in which the text is 

* Tbs is not quits true. Tbs implementation of tbs editor doss not silo* tbs *uu (*®> character to appear 
in files. AH'? tbs IT Waofeoa or *J) ebanaer is used by tbs sditor to sepsnis lines in the fils, so it cannot 
wpear m the middle of a line. You can insert any other character, h o wever, if you wan for the editor to 
echo the [ before you type the character. In fas. tbs editor will treat a following latter as a request for the 
corresponding control character. This is the only way to type *S or *Q. since the system normally uses (hem 
to suspend and resume output and never gives them to the editor to proe m 
t The \ character you give will not echo until you type another key. 
t Not available in all v2 editors due to memory constraints. 
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dismayed. 

In cow mode the editor uses a single line window into the file, and moving backward and 
forward in the Ele nure new lines to he displayed, always below the current line. Two com¬ 
mands of w wort differently in open: i and *JL The a command does not take parameters, but 
rather draws a window of context around the current line and then returns you to. the current 

Une. * ' 

If you are on a hardcopy terminal, the *Tt command will retype the current line. On such 
terminals, the editor normally uses two lines to represent the current line. The amto* is a 
coor of the Une » you started to edit iu and you work on the line below this line. When you 
delete characters, the editor types e number of Vs to show you the charatters which are deleted. 
The editor also reprints the: current Une soon after suds changes jo that you on see what the 
Une looks like again. 

It is sometimes useful to use this mode on very slow terminals which can support w in the 
m screen mode. You can do this by enterinf ex and using an open command. 
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Appendix: character functions 

This appendix gives the uses the editor makes of each character. The characters are 
presented in their order in the aSCU character set: Control characters come first, then most 
special characters, then the digits, upper and then lower case characters. 

For each character we tell a meaning it has as a command and any meaning it has during 
an insert. If it has only meaning as a command, then only this is Section numbers 

in parentheses indicate where the character is discussed; a T after the section number means 
that the character is mentioned in a footnote. 

*@ Not a command character. If typed as the first character of an insertion it is 

replaced with the last text inserted, and the insert terminates. Only 128 char¬ 
acters are saved from the last insert; if more characters were inserted the 
mechanism is not available. A *<§ cannot be part of the file due to the editor 
implementation (7JO. 

*A Unused. 

*B Backward window. A count specifies repetition. Two lines of continuity are 

kept if possible (2.1, 6.1, 7.2). 

*C Unused. 

*0 As a command, scrolls down a half-window of text. A count gives the number 

of (logical) lines to scroll, and is remembered for future *D and ~U commands 
(2.1, 7.2). During an insert, backtabs over mtoindent white space at the begin¬ 
ning of a line (6.6, 7 J); this white space cannot be backspaced over. 

T Exposes one more line below the current screen in the file, leaving the cursor 

where it is if possible. (Version 3 only.) 

T Forward window. A count specifies repetition. Two lines of continuity are 

kept if possible (2.1, 6.1, 7.2). 

*G Equivalent to dot. printing the current file, whether it has been modified, the 

current line number and the number of lines in the file, and the percentage of 
the way through the file that you are. 

~H (bs) Same as left arrow. (See h). During an insert, eliminates the last input char¬ 

acter, backing over it but not erasing it; it remains so you can see what you 
typed if you wish to type something only slightly different (3.1. 7J). 

*1 (Tab) Not a command character. When inserted it prints as some number of spaces. 

When the cursor is at a tab character it rests at the last of the spaces which 
represent the tab. The spacing of tabstops is controlled bv the taostop option 
(4.1, 6.6). 

Same as down arrow (see J). 

Unused. 

The ASCH formfeed character, this causes the screen to be cleared and redrawn. 
This is useful after a transmission error, if characters typed by a program ocher 
than the editor scramble the screen, or after output is stopped by-an interrupt 
(5.4, 7JD. 

A carriage return advances to the next line, at the first non-wbite position in 
the line. Given a count, it advances that many lines (2J). During an insert, a 
at causes the insert to continue onto another line (3.1). 

Same as down arrow (see j). 

Unused. 


*J (L5) 

•x 

*L 


*M (ex) 

*N 

*0 
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*? 

*Q 

*R 

*S 

*T 

“U 


*V 

**W 

*1 

*Y 

*2 

*1 (ssc). 


*\ 

*1 


S?ACS 

f 


Same as up arrow (see It). 

Not a command character. In input mode. ‘Q quotes the next character, the 
same as *V. except that some teletype driven will eat the ‘Q so that the editor 
never sees it. 

Redraws the current screen, eliminating logical lines not corresponding to phy¬ 
sical lines (lines with only a single <§ character on them). On hardcopy termi¬ 
nals in open mode, retypes the current line (5.4, 7.2, 7.3). 

Unused. Some teletype driven use *S to suspend output until *Qis 

Not a command character. During an insert, with autoindent set and at the 
beginning of the line, inserts shifhvidth white space. 

Scrolls the sc re en up, inverting. “D which scrolls down. Counts work as they 
do for *B. and the previous scroll amount is common to both. On a. dumb ter¬ 
minal. *U will often n ec es si tate clearing and redrawing the screen further back 
in the file (11. 7.2). 

Not a command character. In input mode, quotes the next character so that it 
is possible to insert non-printing and special characters into the file (4.2 7.5). 

Not a command character. During an insert, backs up as b would in command 
mode; the deleted characters remain on the display (see *H) (7.5). 

Unused. 

Exposes one more line above the current screen, leaving the cursor where it is 
if possible. (No mnemonic value for this key; however, it is next to *TJ which 
scrolls up a bunch.) (Version 3 only.) 

If supported by the Unix system, stops the editor, exiting to the top level shell. 
Same as stopCR. Otherwise, unused. 

Canc el s a partially formed command, such as a z when no following character 
has yet been given; terminates inputs on the last line (read by commands such 
as : / and ?); ends insertions of new text into the buffer. If an esc is given 
when quiescent in command state, the editor rings the bell or dashes the 
screen. You can thus hit ESC if you don't know what is happening till the edi¬ 
tor rings the belL If you don’t know if you are in insert mode you can type 
ESCa. and then material to be input; the material will be inserted correctly 
whether or not you were in insert mode when you started (1.5, 3.1. 7.5). 

Unused. 

Searches for the word which is after the cursor as a tag. Equivalent to typing 
aa. this word, and then a CR. Mnemonically, this command is “go right to’* 
(7J). 

Equivalent to :a #CR. returning to the previous position in the last edited file, 
or editing a file which you specified if you got a 'No write sines last change 
dia gn ostic’ and do not want to have to type the file name again (7.5). (You 
have to do a nr before *f win work in this case. If you do not wish to write 
the file you should do :*! #CR instead.) 

Unused. Reserved as the command character for the Tektronix 4025 and 4027 
terminal. 

Same as right arrow (see I). 

An operator, which processes lines from the buffer with reformatting com¬ 
mands. Follow ! with the object to be processed, and then the command name 
terminated by CR. Doubling ! and preceding it by a count causes count lines to 
be filtered; otherwise the count is passed on to the object after the !. Thus 
Hl/nttCR reformats the next two paragraphs by running them through the pro¬ 
gram fmt If you are working on US?, the command !%grmcCR.* given at the 


‘Both fm ana inmt an Berkeley programs and may aot be present at all installations. 





beginning of a function. will run the text of the function through the us? 
grinder (6.7, 7.3). To read a file or the output of a command into the buffer 
use 7 (7J). To simply execute a command use :! (7J). 

Precedes a named buffer specification. There are named buffers 1-9 used for 
saving deleted text and named buffers a—x into which you can place text (4.3 
6J) 

The macro character which, when followed by a number, will substitute for a 
function key on terminals without function keys (6.9). In input mode, if this 
is your erase character, it will delete the last character you typed in input 
mode, and must be preceded with a \ to insen it. since it normally backs over 
the last input character you gave. 

Moves to the end of the current line. If you s* listen, then the end of each 
line will be shown by printing a S after the end of the displayed text in the 
line. Given a count, advances to the count'th following end of line: thus 2S 
advances to the end of the following line. 

Moves to the parenthesis or brace { } which balances the parenthesis or brace 
at the current cursor position. 

A synonym for ikCX, by analogy with the ex & command. 

When followed by a ’ returns to the previous context at the beginning of a 
line. The previous context is set whenever the current line is moved in a 
non-relative way. When followed by a letter a—z. returns to the line which 
was marked with this letter with a m command, at the first non-white character 
in the line. iX2, JJ). When used with an operator such as d. the operation 
takes place over complete lines: if you use '. the operation takes place from the 
exact marked place to the current cursor position within the line. 

Retreats to the beginning of a sentence, or to the beginning of a us? s- 
expression if the lisp option is set. A sentence ends at a .! or 7 which is fol¬ 
lowed by either the end of a line or by two spaces. Any number of dosing ) I 
* and ' characters may appear after the . ! or ?, and before the spaces or end of 
line. Sentences also begin at paragraph and secuon boundaries (see { and (I 
below). A count advances that many sentences (4.2. 6.3). 

Advances to the beginning of a sentence. A count repeats the effect. See ( 
above for the definition of a sentence (4.2. 6.8). 

Unused. 

Same as CR when used as a command. 

Reverse of the last f F t or T command, looking the other way in the current 
line. Especially useful after himngtoo many ; characters, a count repeats the 
search. 

Retreats to the previous line at the first non-white character. This is the 
inverse of + and RETURN. If the line moved to is not on the screen, the 
screen is scrolled, or deared and redrawn if this is not possible. If a large 
amount of scrolling would be required the screen is also deared and redrawn, 
with the current line at the center (2J). 

Repeats the last command which changed the buffer. Especially useful when 
deleting words or lines: you can delete some words/lines and then hit . to 
delete more and more words/lines. Given a count, it passes it on to the com¬ 
mand being repeated. Thus after a 2dw, 3. deletes three worts G»3. 6.3. 7.2. 
7.4). 







Reads a suing from the Iasi line on the screen, and scans forward for the next 
occurrence of this suing. The normal input editing sequences may be used 
during the input on the bottom line; an returns to command state without ever 
searching. The search begins when you hit Cl to terminate the pattern; the 
cursor moves to the beginning of the last line to indicate that the search is in 
progress; the search may then be terminated with a DEL or rub. or by back* 
spacing when at the beginning of the bottom line, returning the cursor to its 
j pjtigi position. Searches normally wrap end-around to find a string anywhere 
in the buffer. 

When used with an operator the enclosed region is normally affected. By men¬ 
tioning an offset from the line matched by the pattern you can force whole 
lines to be affected. 'To do this give a pattern with a dosing a dosing / and 
then an offset +e or — n. 

To indude the daxvasr / in the search string, you must escape it with a 
preceding \. A t at the beginning of the pattern forces the match to occur at 
the beginning of a line only; this speeds the search. A S at die end of the pat¬ 
tern forces the match to occur at the end of a line only. More extended pat¬ 
tern matching is available, see section 7.4; unless you set oomagic in your 
.ecrc file you will have to preceed the characters . I • and * in the search pat¬ 
tern with a \ to get them to work as you would naively expect (l_5. 2.2. 6.1. 
7.2. 7.4). 

Moves to the first da nger on the current line. Also used, in forming 
numbers, after an initial 1“9. 

Used to form numeric arguments to co mm a n ds (2-3, 12). 

A prefix to a set of commands for file and option manipulation and escapes to 
the system. Input is given on the bottom line and terminated with an d. and 
the refflfflanrf then executed. You can return to where you were by hitting 
DEL or RUB if*you hit; accidentally (see primarily 6.2 and 7J). 

Repeats the last single character find which used f F t or T. A count iterates 
the basic scan (4.1). 

An operator which shifts lines left one shifrnidth, normally 3 spaces. Like all 
operators, affects lines when repeated, as in < <. Counts are passed through 
to the basic object, thus 3< < shifts three lines (6.6, 7.2). 

Reindents line for US?, as though they were typed in with lisp and autoindent 
set (6.3). 

An operator which shifts lines right one shiftwidxiu normally 8 spaces. Affects 
li ne rs when repeated as in > >. Counts repeat the basic object (6.6. 7.2). 

backwards, the opposite of /. See the / description above for details on 
scanning (2.2. 6.1, 7.4). 

A macro character (6.9). If this is your kill character, you must escape it with 
a \ to type it in during input mode, as it normally backs over the input you 
have given on the current line (3.1, 3.4. IS). 

Appends at the end of line, a synonym for Sa (7.2). 

flar-w up a word, where words are composed of non-blank sequences, placing 
the cursor at the beginning of the word. A count repeats the enect 12.4). 

the rest of the text on the current line; a synonym for cS. 

Deletes the res: of the text on the current line; a synonym for dS. 
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E Moves forward to tbe end of a word, defined as blanks and non-blanks. like B 

and W. A count repeats tbe effect. 

F Finds a single following character.- backwards in the current line. A count 

repeats this search that many times (4.1). 

C Goes to the line number given as preceding argument, or the end of the file if 

no preceding count is given. The screen is redrawn with the new current line 
in the center if necessary (7.2). 

H Home arrow. Homes the cursor to the top line on the screen. If a count is 

given, then tbe cursor is moved to the count’th line on the screen. In any case 
the cursor is moved to the first non-white character on the line. If u ?fd as the 
target of an operator, full lines are affected (2J. 3.2). 

I Inserts at the beginning of a line; a synonym for fL 

J Joins, together lines, supplying appropriate white space: one space between 

words, two spaces after a „ and no spaces at all if the first character of the 
joined on line is ). A count causes that many lines to be joined rather than the 
default two (6-5, 7.1 f). 

Unused. 

Moves the cursor to the first non-white character of the last line on the screen. 
With a count, to the first non-white of the count’th line from the bottom. 
Operators affect whole lines when used with L (2J). 

M Moves the cursor to the middle line on the screen, at the first non-white posi¬ 

tion on the line (2-3). 

N Scans for the next match of the last pattern given to / or 7. but in tbe reverse 

. direction; this is the reverse of n. 

0 Opens a new tine above the currant line and inputs text there up to an esc A 

count can be used on dumb terminals to specify a number of line s to be 
opened; this is generally obsolete, as the sbwopen option works better (3.1). 

P Puts the last deleted text back before/above the cursor. Tbe text goes back as 

whole lines above the cursor if it was deleted as whole lines. Otherwise the 
text is-inserted between the characters before and at the cursor. May be pre¬ 
ceded by a named buffer spe c ifi c a ti on *x to retrieve the contents of the buffer: 
buffers 1—9 contain deleted material, buffers a—a are available for general use 
(6.3). 

Q Quits from n to ex command mode. In this mode, whole lines form com¬ 

mands. ending with a RETURN. You can give all the : e p m manti s; the editor 
supplies the : as a prompt (7.7). 

R Replaces cha r a ct e r s on the screen with characters you type (overlay fashion). 

Terminates with an esc 

S C ha n ges whole lines, a synonym for cc. A count substitutes for that many 

lines. Tbe lines are saved in the numeric buffers, and erased on the screen 
before the substitution begins. 

T Takes a single following character, locates the character before the cursor in 

the current line, and places the cursor just after that character. A count 
repeats the effect Most useful with operators such as d (4.1). 

Restores the currant line to its state before you started changing it (3.5). 

Unused. 


U 

V 






Moves forward to tht beginning of s word is tbo current line, where words are 
defined as sequences of blsnk/non-blink chsracters. A couni repeats the effect 

a*). 

Deietes the character before the cursor. A count repeats the effect, but only 
characters on the current line are deleted. 

Yanks a copy of the current line Into the unnamed buffer, to be put back by a 
later p or P; a very useful synonym for yy. A count yanks that many lines. 
May be preceded by a buffer name to put lines in that buffer (7.4). 

Exits the editor. (Same as mOL) If any changes have been made, the buffer is 
written out to the current file. Then the editor quits. 

up to the previous section boundary. A section begins at each macro in 
the sections option., normally t \NH’ or SK and also at lines which which 
start with a formfeed *1. Lines beginning with { also stop U: this makes it 
useful for looking backwards, a ftmedon at a time. In C programs. • Ir the 
option top is set, stops at each (it the beginning of s line, and is thus useful 
for moving backwards at the top level US? objects. (4.2. 6.1. 6.6. 7.2). 

Un u se d . 

Forward to a section boundary, see It for a de fi nition (4.2.6.1. 6.6.7.2). 

Moves to the first non-white position on the current line (4.4). 


When followed by a * returns to the previous context. The previous context is 
set whenever* the current line is moved in s non-relative way. When followed 
by a letter a-*, returns to the position which was marked with this letter with 
a m command. When used with an operator such as d. the operation take 
place from the exact marked place to the current position within the line; if 
you usethe operation takes place over complete lines (2.2. 5J). 

Appends arbitrary text after the current cursor position; the insert can continue 
onto multiple lines by using RETURN within the insert. A count causes the 
inserted text to be replicated* but only if the inserted text is all on one line. 
The insertion terminates with in ESC (3.1, 7.2). 

up to the beginning of a word in the current line. A word is a sequence 
of alphanumeric*. or a sequence of special characters. A count repeats the 
effect (14). 

An operator which changes the following object, replacing it with the following 
input text up to an ESC If more than pan of a single line is affected, the text 
which is changed away is raved in the numeric named buffers. If only part of 
the current line is affeerad. then the last character to be changed away is 
marked with a 1 A count causes that many objects to be affesned. thus both 
3c) and c3) change the following three sentences (7.4). 

An operator which deletes the following object. If more than pan of a line is 
affected, the text is saved in the numeric buffers. A count causes that many 
objects to be affecrad; thus 3dw is the same as 43w (3J, 3.4, 4.1. 7.4). 
Advances to the end of the next word, defined as for b and w. A count 
repeats the effect (14. 3.1). 

Finds the first instance of the next character following the cursor on the 
current line. A count repeats the find (4,1). 

Unused. 

Arrow keys h. j. k. 1. and H. 




Left arrow. Moves the cursor one character to the left. Like the other arrow 
keys, either h. the left arrow key. or one of the synonyms (*H) has the same 
effect. On v2 editors, arrow keys on certain kinds of terminals (those which 
send escape sequences, such as vt52> cl 00. or bp) cannot be used. A count 
repeats the effect (3.1, 7.5). 

Inserts text before the cursor, otherwise like a (7.2). 

Down arrow. Moves the cursor one line down in the same column. If. the 
position does not exist, W comes as dose as possible to the same column. 
Synonyms indude *J (linefeed) and *N. 

Up arrow. Moves the cursor one line up. *? is a synonym. 

Right arrow. Moves the cursor one character to the right, space is a 
synonym. 

Marks the current position of the cursor in the mark register which is specified 
by the next character a—z. Return to this position or use with an operator 
using ' or * (5 J). 

Repeats the last / or ? scanning commands (22). 

Opens new lines below the current line; otherwise like 0 (3.1). 

Puts text after/beiow the cursor; otherwise like P (6J). 

Unused. 

Replaces the single character at the cursor with a single character you type. 
The new character may be a RETURN; this is the easiest way to split lines. A 
count replaces each of the following count characters with the single character 
given; see R above which is the more usually useful iteration of r (3.2). 

Changes the single character under the cursor to the text which follows up to 
an ESC; given a count, that many characters from the current line are changed. 
The last character to be changed is marked with S as in c (32). 

Advances the cursor upto the character before the next character typed. Most 
useful with operators such as d and c to delete the characters up to a following 
character. You can use . to delete more if this doesn’t delete enough the first 
time (4.1). 

Undoes the last change made to the current buffer. If repeated, will alternate 
between these two states, thus is its own inverse. When used after an insen 
which inserted text on more than one line, the lines are saved in the numeric 
named buffers (3 J). 

Unused. 

Advances to the beginning of the next word, as defined by b (2.4). 

Deletes the single character under the cursor. With a count deletes deletes 
that many characters forward from the cursor position, but only on the current 
line (6J). 

An operator, yanks the following object into the unnamed temporary buffer, if 
preceded by a named buffer specification, 'x. the text is placed in that buffer 
also. Text can be recovered by a later p or P (7.4). 

Redraws the screen with the*current line placed as specified by the following 
character RETURN specifies the top of the screen. . the center of the screen, 
and — at the bottom of the screen. A count may be given after the z and 
before the following character to specify the new screen size for the redraw, a 
count before the z gives the number of the line to place in the center of the 
screen instead of the default current tine. (5.4) 
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Retreats to the beginning of the beginning of the preceding paragraph. A para* 
graph begins at each macro in the paragraphs option, normally \IP\ *.LP\ 
‘ JP’, \QP’ and \bp\ A paragraph also begins after a completely empty line, 
and at each section boundary (see II above) (4.2.6.3. 7.6). 

Places the cursor on the character in the column specified by the count (7.1. 
7.2). 

Advances to the beginning of the next paragraph. See ( for the definition of 
paragraph (4.2, 6.3. 7.6). 

Unused. 

Interrupts the editor, returning it to command accepting state (1.5. 7.5) 


*? (DEL) 





Edit: A Tutorial 




This narrative introduction to the use of the text editor edit assumes no prior 
familiarity with computers or with text editing. Its aim is to lead the beginning 
UNIX user through the fundamental steps of writing and revising a file of text. 
Edit, a version of the text editor sx, was designed to provide an informative 
environment for new casual users. 

This edition documents Version Z of sdif and cx. 

We welcome comments and suggestions about this tutorial and the UNIX docu¬ 
mentation in general. 
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Text editing using a terminal connected to a computer allows one to create, modify, and 
print text easily. A specialized computer program, known as a text editor . assists in creating and 
revising text. Creating text is very much like typing on an electric typewriter. Modifying text 
involves telling the text editor what to add. change, or delete. Text is printed by giving a com¬ 
mand to print the file contents, .with or without special instructions as to the format of the 
desired output. 

These lessons assume no prior familiarity with computers or with text editing. They con¬ 
sist of a series of text editing sessions which will lead you through the fundamental steps of 
creating and revising a file of text. After scanning each lesson and before beginning the next, 
you should follow the examples at a terminal to get a feeling for the actual process of text edit¬ 
ing. Set aside some time for experimentation, and you will soon become familiar with using 
the computer to write and modify text In addition to the actual use of the text editor, other 
features of UNIX will be very Important to your work. You can begin to leant about these other 
features by reading “Communicating with UNIX” or one of the other tutorials which provide a 
general introduction to the system. You will be ready to proceed with this lesson as soon as 
you are familiar with your terminal and its special keys, the login procedure, and the ways of 
correcting typing errors. Let’s first define some terms: 


program 

UNIX 

edit 


file 


filename 


A set of instructions given to the computer, describing the sequence of steps 
which the computer performs in order to accomplish a specific task. As an exam¬ 
ple. a series of steps to balance your checkbook is a program. 

UNIX is a special type of program, called an operating system, that supervises the 
machinery and all other programs comprising the total computer system. 

edit is the name of the UNIX text editor which you will be learning to use. a pro¬ 
gram that aids you in writing or revising text. Edit was designed for beginning 
users, and is a simplified version of an editor named ex. 

p*rh t'NlX account is allotted space for the permanent storage of information. 
fnrfi as programs, data or text. A file is a logical unit of data, for example, an 
essay, a program, or a chapter from a book, which is stored on a computer system. 
Once you create a file it is kept until you instruct the system to remove it. You 
may create a file during one UNIX session, log out. and return to use it at a later 
time. Files contain anything you choose to write and store in them. The sizes of 
files vary to suit your needs*, one file might hold only a single number, and 
another might contain a very long document or program. The only way to save 
information from one session to the hext is to write it to a file, storing it for later 
use. 

Filenames are used to distinguish one file from another, serving the same purpose 
as the labels of manila folders in a file .cabinet. In order to write or access infor¬ 
mation in a file, you use the name of that file in a UNIX command, and the system 
will automatically locate the file. 
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disk Files are stored on an input/output device called a disk, which looks somethin* 

like a suck of phonograph records. Each surface is coated with a material simiiar 
to the coating on magnetic recording tape, on which information is recorded. 

buffer A temporary work space, made available to the user for the duration of a session 
of text editing and used for building and modifying the text file. We can imagine 
the buffer as a blackboard that is erased after each class, where each session with 
the editor is a class. 


' Session l: Creating a File of Text 

To use the editor you must first make contact with the computer by logging in to UNIX. 
We’ll quickly review the standard UNIX login p rocedure. 

If the terminal you are using is directly linked to the computer, turn it on and press car¬ 
riage return, usually labelled “RETURN". If your terminal connects with the computer over a 
telephone line, turn on the terminal, dial the system access number, and. when you hear a 
high-pitched tone, place the receiver of the telephone in the acoustic coupler. Press carriage 
return once and await the login message: 

dogim 

Type your login name, which identifies you to UNIX, on the same line as the login mes¬ 
sage. and press carriage return. If the terminal you are using has both upper and lower case, be 
sure you enter your login name in lower case; otherwise UNIX assumes your terminal has only 
upper case and will not recognize lower case letters you may type. UNIX types “Jogin:” and 
you reply with your login name, for example “susan": 

•Jogin: susan (end press carnage return) 

(In the examples, input typed by the user appears in bold face to distinguish it from the 
responses from UNIX.) 

Unix will next respond with a request for a password as an additional precaution to 
prevent unauthorized people from using your account. The password will not appear when you 
type it to prevent others from seeing it. The message is: 

Password: (type your password and press carriage return) 

If any of the information you gave during the login sequence was mistyped or incorrect UNIX 
will respond with 

Login incorrect. 

-Jogin: 

in which case you should Stan the login process anew. Assuming that you have successfully 
logged in. UNIX will print the message of the day and eventually will present you with a '#> at 
the beginning of a fresh line. The % is the UNIX prompt symbol which tells you that unix is 
ready to accept a command. 

Asking for edit 

You are ready to tell UNIX that you want to work with edit, the text editor. Now is a con¬ 
venient time to choose a name for the file of text which you are about to create. To begin your 
editing session type edit followed by a space and then the filename which you have selected, for 
example “text”! When you have completed the command, press carriage return and wait for 
edit's response: 
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% edit text (followed by a carriage return) 

’text* No such file or directory 

If you typed the command correctly, you will now be in communication with edit. Edit has sec 
aside a buffer for use as a temporary working space during your current editing session. It also 
checked to see if the file you named, “text”, already existed. As we expected, it was unable to 
find such a file since “text” is the name of the new file that we will create. Edit confirms this 
with the line: 

’text’ No such file or directory 

On the next line appears edit’s prompt announcing that edit expects a command from you. 
You may now begin to create the new file. 

The “Command not found” message 

If you misspelled edit by typing, say. “editor”, your request would be handled as follows: 
% editor 

editor Command not found. 

% 

Your mistake in calling edit “editor” was treated by UNIX as a request for a program named 
“editor”. Since there is no program named “editor”, UNIX reported that the program was “not 
found.” A new % indicates that UNIX is ready for another command, so you may enter the 
correct command. 

A summary 

Your exchange with UNIX as you logged in and made contact with edit should look some¬ 
thing like this: 

'.login: susan 
Password: 

„ a Message of General Interest... 

% edit text 

’text* No such file or directory 
• 

Entering text 

You may now begin to enter text into the buffer. This is done by appending text to what¬ 
ever is currently in the buffer. Since there .is nothing in the buffer at the moment, you are 
appending text to nothing: in effect, you are creating text. Most edit commands have two 
forms: a word which describes what the command dees and a shorter abbreviation of that word. 
Either form may be used. Many beginners find the full command names easier to remember, 
but once you are familiar with editing you may prefer to type the shorter abbreviations. The 
command to input text is “append” which may be abbreviated “a”. Type append and press 
carriage return. 

% edit text 
:append 

Messages from edit 

If you make a mistake in entering a command and type something that edit does not 
recognize, edit will respond with a message intended to help you diagnose your error. For 
example, if you misspell the command to input text by typing, perhaps, "add” instead of 
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"append” or "a”, you will receive this message: 

:add 

add: Not an editor command 

When you receive a diagnostic message, check what you typed in order to determine what part 
of your command confused edit. The message above means that edit was unable to recognize 
your mistyped command and. therefore, did not execute it. Instead, a new appeared to let 
you know that edit is again ready to receive a command. 

Text input mode 

3 y giving the command "append” (or using the abbreviation "a”), you entered text input 
mode, also known as append mode. When you enter text input mode, edit responds by doing 
nothing. You will not receive any prompts while in text input mode. This is your signal that 
vou are to begin entering lines of text. You can enter pretty much anything you want on the 
lines. The lines are transmitted one by one to the buffer and held there during the editing ses¬ 
sion. You may append as much text as you want, and when you wish to stop entering text lines 
you should type a period as the only character on'the line and press carriage return. When you give 
this signal that you want to stop appending text, you will exit from text input mode and reenter 
command mode. Edit will again prompt you for a command by priming 

Leaving append mode does not destroy the text in the buffer. You have to leave append 
mode to do anv of the other kinds of editing, such as changing, adding, or printing text. If you 
type a period as the first character and type any other character on the same line, edit wiU 
believe you want to remain in append mode and will not let you out. As this can be very frus¬ 
trating, be sure to type only the period and carriage return. 

This is as good a place as any to learn an important lesson about computers and text: a 
btknk space is a character as far as a computer is concerned. If you so much as type a period 
followed by a blank (that is. type a period and then the space bar on the keyboard), you will 
remain in append mode with the last line of text being. 

* • 

Let’s say that the lines of text you enter are (try to type exactly what you see, including 
"thiss”): 

This is some sample text. 

And thiss is some more text. 

Text editing is strange, but nice. 

• 

The last line is the period followed by a carriage return that gets you out of append mode. If 
while typing the line you hit an incorrect key. recall that you may delete the incorrect character 
or cancel the entire line of input by erasing in the usual way. Refer to “Communicating with 
UNIX” if you need to review the procedures for making a correction. Erasing a character or 
cancelling a line must be done before the line has been completed by a carriage return. We will 
changes in lines already typed in session 2. 

Writing text to disk 

You are now ready- to edit the text. The simplest kind of editing is to write it to disk as a 
file for safekeeping after the session is over. This is the only way to save information from one 
session to the next, since the editor’s buffer is temporary and will last only until the end of the 
editing session. Thus, learning how to write a file to disk is second in importance only to enter¬ 
ing the text. To write the contents of the buffer to a disk file, use the command "write'' tor its 
abbreviation "w"): 



: wriie 


• 5. 


Edit will copy the buffer to a disk file. If the file does not yet exist, a new file will be created 
automatically and the presence of a “New file” will be noted. The newly-created file will be 
given the name specified when you entered the editor, in this case “text”. To confirm that the 
disk file has been successfully written, edit will repeat the filename and give the number of 
lines and the total number of characters in the file. The buffer remains unchanged by the 
“write” command. All of the lines which were written to disk will still be in the buffer, should 
you want to modify or add to them. 

Edit must have a filename to use before it can write a file. If you forgot to indicate the 
name of the file when you began the editing session, edit will print 

No current filename 

in response to your write command. If this happens, you can specify the filename in a new 
write command: 

: write text 

After the “write” (or “w") type a space and then the name of the file. 

Logging off 

We have done enough for this first lesson on using the UNIX text editor, and are ready to 
quit the session with edit. To do this we type “quit” (or “q”) and press carriage return: 

: write 

•text" (New file] 3 lines. 90 characters 
:quit 
% 

The % is from UNIX to tell you that your session with edit is over and you may command UNIX 
further. Since we want to end the entire session at the terminal we also need to exit from 
UMX. In response to the UNIX prompt of “%” type the command logout or a “control d”. 
This is done by holding down the control key (usually labelled “CTRL”) and simultaneously 
pressing the d key. This will end your session with UNIX and will ready the terminal for the 
next user. It is always important to logout at the end of a session to make absolutely sure no 
one could accidentally stumble into your abandoned session and thus gain access to your files, 
tempting even the most honest of souls. 

This is the end of the first session on UNIX text editing. 






• 6 


Session 2 

Login .with UNIX as in the first session: 

'.login: susan (carriage return) 

Password: (jive password and carriage return) 

% 

This time when you say that you want to edit, you can specify the name of the file you worked 
I^ast time This will start edit working and it will fetch the contents of the file into the 
buffer* so L?ou « ££ne editing the same file. When edit has copied the file into the 
buffer, it will repeat its name and tell you the number of lines and characters u contains. Thus. 

% edit text 

'text* 3 lines. 90 charuners 

means vou asked edit to fetch the file named “text” for editing, causing it to copy the 90 char¬ 
acters of text into the buffer. Edit awaits your further instructions. In this session, we will 
append more text to our file, print the contents of the buffer, and learn to cnange the text of a 

line. 

Adding more text to the file 

If you want to add more to the end of your text you may do so by using the append com¬ 
mand to enter text input mode. When append is the first command of your editing session, the 
Cm you enter are placed at the end of the buffer. We ll soon discuss why this happens. Here 
fwe’U use the abbreviation for the append command, a : 

:a 

This is text added in Session 2. 

It doesn’t mean much here, but 
it does illustrate the editor. 


Interrupt 

Should you press the RUBOUT key (sometimes labelled DELETE) while working with edit, it 
will send this message to you: 

Interrupt 

*ny command that edit might be executing is terminated by rubout or delete, causing _ edit to 
. prompt you for a new command. If you are appending text at the time, you will exit from 
^append mode and be expected to give another command. The line of text that you were typing 
’when the append command was interrupted will not be entered into the buffer. 

Making corrections 

If vou have read a general introduction to UNIX, such as “Communicating with UNIX”, 
you will recall that it is possible to erase individual letters that you have typed. This .s done by 
typing the designated erase character as many times as there are cnaracters you want to erase. 
Accounts normally start out using the number sign (*> as the erase character, but u a possio e 
£r a different erase character to be seiectedf. We'U show as the erase character m our 

♦VNtx accounumay be 'personalized" in oilier ways. too. If you're using an established account. met* »«h 
someone who is familiar with your account to find oui if it has any other non-standard cnaransnstws -mch 
msv affect your wort. Accounts for students in classes are otten given dass commands and other specal 
features; the teaching assistant or instructor ts the best source of information about these cnanges. 
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examples, but if you've changed your erase character to backspace (control*H) or something 
else, be sure to use your own erase character. 

If you make a bad start in a line and would tike to begin again, erasing individual charac¬ 
ters with a is- cumbersome — what if you had 15 characters in your line and wanted to get 
rid of them? To do so either requires: 

This IS yukky ttTiifrfififrfi f i fif i fififif rfifif 

with no room for the great text you’d like to type. or. 

This la yukky texOThis Is great text. 

When you type the at-sign (@). you erase the entire line typed so far. (An account may select 
a different line erase character to use in place of @. If your line erase character has been 
changed, use it where the examples show “<§”.) You may immediately begin to retype the 
line. This, unfortunately, does not help after you type the line and press carriage return. To 
make corrections in lines which have been completed, it is necessary to use the editing com¬ 
mands covered in this session and those that follow. 

Listing what’s in the buffer 

Having appended text to what you wrote in Lesson l. you might be curious to see what is 
in the buffer. To prim the contents of the buffer, type the command: 

:l,Sp 

The “1” stands for line l of the buffer, the ‘*5** is a special symbol designating the last line of 
the buffer, and “p” (or print) is the command to print from line 1 to the end of the buffer. 
Thus. “l.Sp” gives you: 

This is some sample text. 

And thiss is some more text 
Text editing is strange, but nice. 

This is text added in Session 2. 

It doesn’t mean much here, but 
it does illustrate the editor. 

Occasionally, you may enter into the buffer a character which can’t be printed, which is done by 
striking a key while the CTRL key is depressed. In printing lines, edit uses a special notation to 
show the existence of non-printing characters. Suppose you had introduced the non-printing 
character “control-A” into the word “illustrate” by accidently holding down the cnu. key 
while typing “a”. Edit would display 

it does illustr'Ate the editor. 

if you asked to have the line printed. To represent the control-A. edit shows “*A”. The 
sequence ***** followed by a capital letter stands for the one character entered by holding down 
the CTRL key and typing the letter yhich appears after the “***. We’ll soon discuss the com¬ 
mands which can be used to correct this typing error. 

In looking over the text we see that “this” is typed as “thiss” in the second line, as sug¬ 
gested. Let’s correct the spelling. 

Finding things in the buffer 

In order to change something in the buffer we first need to find it. We can find "thiss’’ 
m the text we have entered by looking at a listing of the lines. Physically speaking, we search 
the lines of text looking for "thiss” and stop searching when we have found it. The way to tell 
edit to search for something is to type it inside slash marks: 




;/thiss/ 

Bv tvping /thiss/ and pressing carriage return edit is instructed to search for “thiss*;. If we 
asked edit to look for a pattern of characters which it could not find in the buffer, it would 
respond “Pattern not found" When edit finds the characters “thiss". it will prim the line of 

text for your inspection: 

And thiss is some more text. 

Edit is now positioned in the buffer at the line which it just printed, ready to make a change in 
the line. 

The current line 

At ail times during an editing session, edit keeps track of the line in the buffer where it is 
positioned. In general, the line which has been most recently printed, entered, or changed is 
considered to be the current position in the buffer. The editor is prepared to make changes at 
the current position in the buffer, unless you direct it to act in another location. When you 
bring a file into the editor, you will be positioned at the last line in the file. If your initial edit¬ 
ing command is “append", the lines you enter are added to the end of the file, that is. they are 
plac-d after the current position. You can refer to your current position in the buffer by the 
symbol period (.) usually known by the name "dot**. If you type and carriage return you 
will be instructing edit to print the current line: 

• • 

And thiss is some more text. 

If you want to know the number of the current line, you can type .« and carriage return, 
and edit* will respond with the line number 

• • * 

2 

If-you type the number of any line and a carriage return, edit will position you at that line and 
print its contents: 

• 2 

And thiss is some more text. 

You should experiment with these commands to assure yourself that you understand what they 
do. 

Numbering lines (nu) 

Tne number (nu) command is similar to print, giving both the number and the text of 
primed line. To see the number and the text of the current line type 

:nu 

2 And thiss is some more text. 

Notice that the shortest abbreviation for the number command is "nu** (and not “n" which is 
used for a different command). You may specify a range of lines to be listed by the number 
command in the same way that lines are specified for print, ror example. “l.5nu lists ail 
lines in the buffer with the corresponding line numbers. 

Substitute command (s) 

Now that we have found our misspelled word it is time to change it from “thiss" to 
“this". As far as edit is concerned, changing things is a matter of substituting one thing for 
another. As a stood for append, so s stands for substitute. W« will use the abbreviation “s" :o 
reduce the chance of mistyping the substitute command. Tnis command will instruct edit to 
make the change: 
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2 s/ thiss/ this/ 

We first indicate the line to be changed, line 2. and then type an “s” to indicate we want sub* 
stitution. inside the first set of slashes are the characters that we want to change, followed by 
the characters to replace them and then a dosing slash marie. To summarize: 

2 s/ what is to be changed / w hat to change to / 

If edit finds an exact match of the characters to be changed it will make the change only in the 
first occurrence of the characters. If it does not find the characters to be changed it will 
respond: 

Substitute pattern match failed 

indicating your instructions could not be carried out. When edit does find the characters which 
you want to change, it will make the substitution and automatically print the changed line, so 
that you can check that the correct substitution was made, in the example. 

: Zs/thiss/this/ 

And this is some more text. 

line 2 (and line 2 only) will be searched for the characters “thiss”, and when the first exact 
match is found, “thiss” will be changed to “this”. Strictly speaking, it was not necessary 
above to spedfy the number of the line to be changed. In 

: s/thiss/this/ 

edit will assume that we mean to change the line where we are currently positioned In 

this case, the command without a line number would have produced the same result because 
we were already positioned at the tine we wished to change. 

For another illustration of substitution we may choose the line: 

Text editing is strange, but nice. 

We might like to be a bit more positive. Thus, we could take out the characters “strange, 
but “ so the line would read: 

Text editing is nice. 

A command which will first position edit at that line and then make the substitution is: 
:/strange/s/strange, but // 

What we have done here is combine our search with our substitution. Such combinations 
are perfectly legal. This illustrates that we do not necessarily have to use line numbers to iden¬ 
tify a line to edit. Instead, we may identify the line we want to change by asking edit, to search 
for a specified pattern of letters which occurs in that line. The parts of the above command are: 

/strange/ tells edit to find the characters “strange” in the text 

s tells edit we want to make a substitution 

/strange, but // substitutes nothing at all for the characters “strange, but ” 

You should note the space after “but” in “/strange, but /". If you do not indicate the 
space is to be taken out. your line will be: 

Text editing is nice. 

which looks a little funny because of the extra space between “is” and “nice”. Again, we real¬ 
ize from this that a blank space is a real character to a computer, and in editing text we need to 
be aware of spaces within a line just as we would be aware of an “a” or a “4”. 


Another wav to list what's in the buffer (2) 

Although the print commend is useful for looking at specific “ nM >"«k'to 
commends on be more convenient for viewing large sections of tent. You can esk se. 
screen full of text at a time by using the command z. If you type 

: lz 

edit will start with line l and continue printing lines, stopping either when the screen of your 
SnS iTfiill^or when the lest line ,n the buffer has been printed. If »ou « to reed the 
next segment of text, give the command 

:z 

IE no starting line number is given for the z command, printing will start at the “current’ line. 
£“is «e ?he toUtae printed, viewing lines in dm buffer one screen full at a ume ts known 
t r r- g Paging can also be used to print a secion of text on a hard-copy terminal. 

Saving the modified text 

This seems to be a good place to pause in our work, and so we should end the second ses¬ 
sion. If you (in haste) type “q” to quit the session your dialogue with edit wiil be. 

:q 

No write since last change (q! quits) 

This is edit’s warning that you have not written the modified contents of the buffer to disk. 
You run the risk of losing the work you have done during the editing session since the latest 
£«™mmanT Since in Uiia leaeon we have n»i wrinen to disk at all. everyth,n, we have 
done would be lost. If we did not want to save the work done dunng this editing session, we 
Would have to type “q!” to confirm that we indeed wanted to end the session immediately, los- 
r.g me cTnt^f *e buffer. However, since .« want to preserve what we have edited, we 

need to say: 


■text' 6 lines, 171 characters 


and then. 


:q 

% logout 

and hang up the phone or cum off the terminal when UNIX asks for a login name, i nis is the 
end of the second session on UNIX text editing. 
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Session 3 


Bringing text into the buffer (e) 

Login to UNIX and make contact with edit. You should try to login without looking at the 
notes, but if you must then by all means do. 

Did you remember to give the name of the file you wanted to edit? That is. did you say 
% edit text 

or simply 

% edit 

Both ways get you in contact with edit, but the first way will bring a copy of the file named 
“text” into the buffer. If you did forget to tell edit the name of your file, you can get it into 
the buffer by saying: 

:e text 

•text* 6 lines. 171 characters 

The command edit, which may be abbreviated “e” when you're in the editor, tells edit that 
you want to erase anything that might already be in the buffer and bring a copy of the file 
“text” into the buffer for editing. You may also use the edit (e) command to change files in 
the middle of an editing session or to give edit the name of a new file that you want to create. 
Because the edit command dears the buffer, you will receive a warning if you try to edit a new 
file without having saved a copy of the old file. This gives you a chance to write the contents 
of the buffer to disk before editing the next file. 

Moving text in the buffer (m) 

Edit ailows you to move lines of text from one location in the buffer to another by means 
of the move (in) command: 

:2,4raS 

This command directs edit to move lines 2. 3. and 4 to the end of the buffer (S). The format 
for the move command is: that you spedfy the first line to be moved, the last line to be moved, 
the move command “m”, and the line after which the moved text is to be placed. Thus. 

:l,6ra20 

would instruct edit to move lines 1 through 6 (indusive) to a position after line 20 in the 
buffer. To move only one line, say, line 4. to a position in the buffer after line 6, the com¬ 
mand would be “4m6”. 

Let’s move some text using the command: 

2 lines moved 

it does illustrate the editor. 

After executing a command which changes more than one line of the buffer, edit tells how 
many lines were affected by the change. The last moved line is printed for your inspection. If 
you want to see more than just the last line, use the print (p), z. or number (nu) command :o 
view more text. The buffer should now contain: 
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This is some sample text 
It doesn’t mean much here, but 
it does illustrate the editor. 

And this is some more text. 

Text editing is nice. 

This is text added in Session 2. 

W« can restore the original order by typing; 

: 4.Smi 

or, combining context searching and the move command: 

: /And this is some/./This is text/m/This is some sample/ 

The problem with combining context searching with the move command is that the chance of 
making a typing error in such a long command is greater than if one types line numbers. 

Copying lines (copy) 

The copy command, is used to make a second copy of specified lines, leaving the original 
lines where they were. Copy has the same format as the move command, for example: 

: 12 JScopy S 

makes a copy of lines 12 through IS. placing the added lines after the buffer’s end (S). Experi¬ 
ment with the copy command so that you can become familiar with how it works. Note that 
tjie shortest abbreviation for copy is “co” (and not the letter “c’ which has another meaning). 

Deleting lines (d) 

Suppose you want to delete the line 

This is text added in Session 2. 

from the buffer. If you know the number of the tine to be deleted, you can type that number 
followed by “delete” or “d”. This example deletes line 4: 

:4d 

It doesn’t mean much here, but 

Here “4” is the number of the line to be deleted and “delete” or “d” is the command to 
delete the line. After executing the deiete command, edit prints the line which has become the 
cunent line 

If you do not happen to know the line number you can search for the line and then delete 
it using this sequence of com man ds : 

:/added in Session 2./ 

This is text added in Session 2. 

:d 

It doesn’t mean much here, but 

The "/added in Session 2./” asks edit to locate and print the next line which contains the indi¬ 
cated text. Once you are sure that you have correctly specified the line that you want to delete, 
you can enter the delete (d) command. In this case it is not necessary to specify a line number 
before the “d”. If no line number is given, edit deletes the current line (“.”). that is. the line 
found by our search. .After the deietion. your buffer should contain: 
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This is some sample text. 

And this is some more text. 

Text editing is nice. 

It doesn't mean much here, but 
it does illustrate the editor. 

To delete both lines 2 and 3: 

And this is some more text. 

Text editing is nice. 

you type 

:2Jd 

which specifies the range ot* lines from 2 to 3. and the operation on those lines — "d" for 
delete. 

Again, this presumes that you lenow the line numbers for the lines to be deleted. If you 
do not you might combine the search command with the delete command as so: 

:/And this Is some/,/Text editing is nice./d 

This tells the editor to start deleting with the next line that contains the characters "And this is 
some" and continue until it has deleted the line containing "Text editing is nice." 

A word or two of caution: 

In using the search function to locate lines to be deleted you should be absolutely sure 
the characters you give as the basis for the search will take edit to the line you want deleted. 
Edit will search for the first occurrence of the characters starting from where you last edited — 
that is. from the line you see primed if you type dot (.). 

A search based on too few characters may result in the wrong lines being deleted, which 
edit will do as easily as if you had meant it. For this reason, it is usually safer to specify the 
search and then delete in two separate steps, at least until you become familiar enough with 
using the editor that you understand how best to specify searches. For a beginner it is not a 
bad idea to double-check each command before pressing carriage return to send the command 
on its way. 

Undo (u) to the rescue 

The undo (u) command has the ability to reverse the effects of the last command. To 
undo the previous command, type **u” or "undo". Undo can rescue the contents of the buffer 
from many an unfortunate mistake. However, its powers are not unlimited, so it is still wise to 
be reasonably careful about the commands you give. It is possible to undo only commands 
which have the power to change the buffer, for example delete, append, move. copy, substi¬ 
tute. and even undo itself. The commands write (w) and edit (e) which interact with disk files 
cannot be undone, nor can commands such as print which do not change the buffer. Most 
importantly, the only command which can be reversed by undo is the last "undo-able" com¬ 
mand which you gave. 

To illustrate, let's issue an undo command. Recall that the last buffer-changing command 
we gave deleted the lines which were formerly numbered 2 and 3. Executing undo at this 
moment will reverse the effects of the deletion, causing those two lines to be replaced in the 
buffer. 

:u 

2 more lines in file after undo 
And this is some more text. 

Here again, edit informs you if the command affects more than one line, and prints the text of 
the line which is now “dot" (the current line). 
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Mora about th« dot (.) and buffer end (S) 

The function assumed by the symbol dot depends on its context. It can be used: 

U to exit from append mode we type dot (and only a dot) on a line and press carriage 
return: 

2. to refer to the line we are at in the buffer. 

Dot can also be combined with the equal sign to get the number of the line currently being 
edited: 

% % 

Thus if we type we are asking for the number of the line and if we type **. * we are ask* 
ing for the text of the line. 

la this editing session and the last, we used the dollar sign to indicate the end of the 
buffer in commands such as print, copy, and move. The dollar sign as a command asks edit to 
print the last line in the buffer. If the dollar sign is combined with the equal sign (5-> edit 
will print the line number corresponding, to the last line in the buffer. 

ukj therefore represent line numbers. Whenever appropriate, these symbols can 
be used in place of line numbers in commands. For example 

:.,Sd 

instructs edit to delete all lines from the current line (.) to the end of the buffer. 

Moving around in the buffer (+ and —) 

It is frequently convenient during an editing session to go tack and re-read a previous 
line. We could specify a context search for a line we want to read if we remember some of its 
text, but if we simply want to see what was written a few. say 3. lines ago. we can type 

-3p 

This tells edit to move back to a position 3 lines before the current line (.) and print that line. 
We can move forward in the buffer similarly: 

+2p 

limn ers edit to print the line which is 2 ahead of our current position. 

You may use “ V and ” in any command where edit accepts line numbers. Line 
numbers s pec ified with “4*" or can be combined to prim a range of lines. The command 

: — l,4*2copy$ 

makes a copy of 4 lines: the current line, the line before it. and the two after it. The copied 
lines will be placed after the last line in the buffer (S). 

Try typing only you will move back one line just as if you had typed “ — Ip". Typ¬ 
ing the command “V works similarly. You might also try typing a few plus or minus signs in 
a row (such as “4-4-4-“) to see edit's response Typing a carriage return alone on a line is the 
equivalent .of typing “4-Ip"; it will move you one line ahead in the buffer and print that line 

If you are at the last line of the buffer and try to move further ahead, perhaps by typing a 
“4*“ or a carriage return alone on the line, edit will remind you that you are at the end ot the 
buffer 

At end-of-Sle’ 

Similarly, if you try to move to a position before the ftrsx line, edit will print one ot these mes¬ 
sages: 
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Nonzero address required on this command 
Negative address — firs: buffer line is 1 

The number associated with a buffer line is the line's '‘address”, in that it can be used to locate 
the line. 

Changing lines (c) 

There may be occasions when you want to delete certain lines and insert new text in their 
place. This can be accomplished easily with the change (c) command. The change command 
instructs edit to delete spedfied lines and then switch to text input mode in order to accept the 
text which will replace them. Let's say we want to change the first two lines in the buffer 

This is some sample text. 

And this is some more text. 

to read 

This text was created with the UNIX text editor. 

To do so. you can type: 

:Uc 

2 lines changed 

This text was created with the UNIX text editor. 


In the command 1.2c we specify that we warn to change the range of lines beginning with 1 and 
ending with 2 by giving line numbers as with the print command. These lines wiU be deleted. 
After a carnage return enters the change command, edit notifies you if more than one line will 
be changed and places you in text input mode. Any text typed on the following lines will be 
insened into the position where lines were deleted by the change command. You will remain 
in text input mode until you exit in the usual way. by typing a period alone on a line. Note 
that the number of lines added to the buffer need not be the same as the number of lines 
deleted. 

This is the end of the third session on text editing with UNIX. 
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Session 4 

This lesson covers several topics, starting with commands which apply throughout the 
buffer, characters with special meanings, and how to issue UNIX commands while in the editor. 
The next topics deal with files: more on reading and writing, and methods of recovering files 
lost in a crash. The final section suggests sources of further information. 

Making commands global (g) 

One disadvantage to the commands we have used for searching or substituting is that if 
vou have a number of instances of a word to change it appears that you have to type the com¬ 
mand repeatedly, once for each time the change needs to be made. Edit, however, provides a 
way to make commands apply to the. entire contents of the buffer — the global (g) command. 

To print all lines containing a certain sequence of characters (say, “text”) the command 
is: 

: g/text/p 

The “g” instructs edit to make a global search for all lines in the buffer containing the charac¬ 
ters “text”. The “p” prints the lines found. 

To issue a global, command, start by typing a “g” and then a search pattern identifying 
the lines to be affected. Then, on the same line, type the command to be executed on the 
identified lines. Global substitutions are frequently useful. For example, to change all 
instances of the word ‘next” to the word “material” the command would be a combination of 
the global search and the substitute command: 

: g/text/s/text/material/g 

Note the “g” at the end of the. global command which instrucs edit to change each and every 
instance of “text” to “material”. If you do not type the “g” at the end of the command only 
the first instance of ‘next” in each line will be changed (tbe normal result of the subsutute 
command). The “g” at the end of the command is independent of the “g” at the beginning. 
You may give a command such as: 

: 14s/text/material/g 

to change every instance of ‘next” in line 14 alone. Further, neither command will change 
“Text” to “material” because “Text” begins with a capital rather than a lower-case t 

Edit does not automatically print the lines modified by a global command. If you want 
the lines to be printed, type a “p” at the end of the global command: 

: g/text/s/text/materiai/gp 

The usual qualification should be made about using the global command in combination with 
any other - in essence, be sure of what you are telling edit to do to the entire buffer. For 
,example. 

:g/ Id 

72 less lines in file after global 

will delete every line containing a blank anywhere in it. This could adversely affect your docu¬ 
ment, since most lines have spaces between words and thus would be deleted. After executing 
the global command, edit will print a warning if the command added or deleted more than one 
line. Fortunately, the undo command can reverse the effects of a global command. You 
should experiment with the global command on a small buffer of text to see what it can do for 
you. 
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More about searching and substituting 

In using slashes to identify a character string that we want to search for or change, we 
have always specified the exact characters. There is a less tedious way to repeat the same string 
of characters. To change “noun’* to “nouns’* we may type either 

:/noun/s/noun/nouns/ 

as we have done in the past, or a somewhat abbreviated command: 

: J noun/s//nouns/ 

In this example, the characters to be changed are not specified - there are no characters, not 
even a space, between the two slash marks which indicate what is to be changed. This lack of 
characters between the slashes is taken by the editor to mean “use the characters we las: 
searched for as the characters to be changed.’* 

Similarly, the last context search may be repeated by typing a pair of slashes with nothing 
between them: 

:/docs/ 

It doesn’t mean much here, but 
:// 

it does illustrate the editor. 

Because no characters are specified for the second search, the editor sans the buffer for the 
next occurrence of the characters “does”. 

Edit normally searches forward through the buffer, wrapping around.from the end of the 
buffer to the beginning, until the specified character string is found. If you want to search in 
the reverse direction, use question marks (?) instead of slashes to surround the character 
string. 

It’s also possible to repeat the last substitution without having to retype the entire com¬ 
mand. An ampersand (&) used as a command repeats the most recent substitute command, 
using the same search and replacement patterns. After altering the current line by typing 

:s/noun/nouns/ 

we could use the command 

: /nouns/<i 

or simply 

://4 

to make the same change on the next line in the buffer containing the characters “nouns". 
Special characters 

Two characters have special meanings when used in specifying searches: “S” and.. 

**S” is taken by the editor to mean “end of the line” and is used to identify strings which 
occur at the end of a line. 

:g/lngS/s//ed/p 

tells the editor to search for ail lines ending in “ing” (and nothing else, not even a blank 
space), to change each final “ing” to “ed” and print the changed lines. 

The symbol indicates the beginning of a line. Thus, 

:s/*/l. / 

instructs the editor to insert “1.” and a space at the beginning of the current line. 

The characters and. have special meanings only in the context of searching. At 
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other times, thev are ordinary characters. If you ever need to search for a character that has a 
special meaning, you must indicate that the character is to temporarily lose its special 
significance by typing another special character, the backslash (\). before it. 

: sAS/dollar/ 

looks for the character “S” in the current line and replaces it by the word “dollar”. Were it 
not for the backslash, the “S” would have represented “the end of the line” in your search, 
rather than the character “S”. The backslash retains its special significance unless it is pre¬ 
ceded by another backslash. 

Issuing UNIX commands from the editor 

After creating several files with the editor, you may want to delete files no longer useful 
to you or ask for a list of your files. Removing and listing files are not functions of the editor, 
'and so they require the use of UNIX system commands (also referred to as “shell” commands, 
as "shell” is the name of the program that processes UNIX commands). You do not need to 
quit the editor to execute a UNIX command as long as you indicate that it is to be sent to the 
shell for execution. To use the UNIX command rm to remove the file named "junk” type: 

: !rm junk 


The exclamation mark (!) indicates that the rest of the line is to be processed as a UNIX com¬ 
mand. If the buffer contents have not been written since the last change, a warning will be 
printed before the command is executed. The editor prints a "!” when the command is com¬ 
pleted. The tutorial “Communicating with UNIX” describes useful features of the system, of 
which the editor is only one part. 

Filenames and file manipulation 

Throughout each editing session, edit keeps track of the name of the file being edited as 
the current filename. Edit remembers as the current filename the name given when you entered 
the editor. The current filename changes whenever the edit (e) command is used to specify a 
new file. Once edit has recorded a current filename, it inserts that name into any command 
where a filename has been omitted. If a write command does not specify a file. edit, as we 
have seen, supplies the current filename. You can have the editor write onto a different file by 
including its name in the write command: 

: w chapter3 

*chapter3* 283 lines, 8698 characters 

The current filename- remembered by the editor will not be changed as a result of the wnte com¬ 
mand unless it is the first filename given in the editing session . Thus, in the next write command 
.which does not specify a name, edit will write onto the current file and not onto the file 
' "chapter3”. 

The file (f) command 

To ask for the current filename, type file (or 0. In response, the editor provides current 
information about the buffer, including the filename, your current position, and the numoer of 
lines in the buffer 

‘text* {Modifiedl line 3 of 4 -75%- 

If the contents of the buffer have changed since the last time the file was written, the editor 
wiil tell you that the file has been "(Modifiedl”. After you save the changes by writing onto a 
disk file.* the buffer will no longer be considered modified: 
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‘text’ 4 lines, 38 characters 
•text* line 3 of 4 -75%- 

Reading additional files (r) 

The read (r) command allows you to add the contents of a file to the buffer without des¬ 
troying the text already there. To use it. specify the line after which the new text will be 
placed, the command r. and then the name of the file. 

: Sr bibliography 

'bibliography' 18 lines. 473 characters 

This command reads in the file bibliography and adds it to the buffer after the last line. Tne 
current filename is not changed by the read command unless it is the -first filename given in the 
editing session. 

Writing parts of the buffer 

The write (w) command can write ail or part of the buffer to a file you specify. We are 
already familiar with writing the entire contents of the buffer to a disk file. To write only part 
of the buffer onto a file, indicate the beginning and ending lines before the write command, for 
example 

: 45,Sw ending 

Here all lines from 45 through the end of the buffer’are wrinen onto the file named ending. 
The lines remain in the buffer as part of the document you are editing, and you may continue 

to edit the entire buffer. 

* 0 

Recovering files 

Under most circumstances, edit’s crash recovery mechanism is able to save work to within 
a few lines of changes after a crash or if the phone is hung up accidently. If you lose the con* 
tents of an editing buffer in a system crash, you will normally receive mail when you login 
which gives the name of the recovered file. To recover the file, enter the editor and type the 
command recover (rec), followed by the name of the lost file. 

: recover chaptf 

Recover is sometimes unable to save the entire buffer successfully, so always check the con* 
tents of the saved buffer carefully before writing it back onto the original file. 

Other recovery techniques 

If something goes wrong when you are using the editor, it may be possible to save your 
work by using the command preserve (pre), which saves the buffer as if the system had 
crashed. If you are writing a file and you get the message “Quota exceeded”, you have tried to 
use more disk storage than is allotted to your account. Proceed with caution because it is likely 
that only a pan of the editor’s buffer is now present in the file you tried to write. In this case 
you should use the shell escape from the editor (!) to remove some files you don’t need and try 
to write the file again. If this is not possible and you cannot find someone to help you. enter 
the command 

: preserve 

and then seek help. Do not simply leave the editor. If you do. the buffer will be lost, and you 
may not be able to save your file. After a preserve, you can use the recover command once the 
problem has been corrected. 
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If you make an undesirable change to the buffer and issue a write command bet ore dis¬ 
covering your mistake, the modified version will replace any previous version of the file. 
Should you ever lose a good version of a document in this way. do not panic and leave the edi- 
tor. As'long as you stay in the editor, the contents of the buffer remain accessible. Depending 
on the nature of the problem, it may be possible to restore the buffer to a more complete state 
with the undo command. After fixing the damaged buffer, you can again write the file to disk. 

Further reading and other information 

Edit is an editor designed for beginning and casual users. It is actually a version of a 
more powerful editor called ex These lessons are intended to introduce you to the editor and 
its more commonly-used commands. We have not covered all of the editor’s commands, just a 
selection of commands which should be sufficient to accomplish most of your editing tasks. 
You can find out more about the editor in the Ex Reference Manual, which is applicable to both 
ex and edit. The manual is available from the Computer Center Library. 213 Evans Hall. One 
way to become familiar with the manual is to begin by reading the description of commands 
that you already know; 

Using ex 

As vou become more experienced with using the editor, you may still find that edit con¬ 
tinues to meet your needs. However, should you become interested in using ex. it is easy to 
switch. To begin an editing session with ex. use the name ex in your command instead of edit. 

Edit commands work the same way in ex, but the editing environment is somewhat 
different. You should be aware of a few differences that exist between the two versions of the 
editor In edit, only the characters —\ “S*\ and “V* have special meanings in searching the 
buffer or indicating characters to be changed by a substitute command. Several additional char¬ 
acters have special meanings in ex. as described in the Ex Reference Manual. Another feature 
of- the edit environment prevents users from accidently entering two alternative modes of edit¬ 
ing, open and visual, in which the editor behaves quite differently than in normal command 
mode If you are using ex and the editor behaves strangely, you may have accidently entered 
open mode by typing **o’\ Type the ESC key and then a ’*Q M to get out of open or visual mode 
and back into the regular editor command mode. The document An Introduction to Display Edit - 
my with Vi provides a full discussion of visual mode. 


This tutorial was produced at the Computer Center of the University of 
California . Berkeley. We welcome comments and suggestions concern¬ 
ing this item and the UNIX documentation in general. 
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1. Starting «x 

Each instance of the editor has a set of options, which can be set to tailor it to your liking. 
The command edit invokes a version of ex designed for more or beginning, users by 

changing the default settings of some of these options. To simplify the description which fol¬ 
lows we assume the default settings of the options. 

When invoked, ex determines the terminal type from the TERM variable in the environ¬ 
ment. It there is a TERMCa? variable in the environment, and the type of the te rminal 
described there m a t ches the TERM variable, then that description is used. Also if the termca? 
variable contains a pathname (beginning with a /) then the editor will seek the description of 
the terminal in that file (rather than the default /etc/termcap.) If there is a variable EXlNrr in 
the environment, then the editor will execute the commands in that variable, otherwise if there 
is a file .exK in your HOME directory ex reads commands from that file. Emulati ng a source com¬ 
mand. Option setting commands placed in EXINIT or .car will be executed before each editor 
session. 

A command to enter ex has the following prototype:! 

•x ( “ ] [ —v 1 [ “t tag 1 ( 1 l ”11 l "wn ) ( “St ] l “R ] I + command ] name ... 

The most common case edits a single file with no options. Le.: 
ex name 

The — command line option option suppresses all interactive-user feedback and is useful in 
pr ocessin g editor scripts in command files. The —▼ option is equivalent to using w rather than 
ex. The —t option is equivalent to an initial tax command, editing the file containing the tag 
and positioning the editor at its definition. The —r option is used in recovering after an editor 
or system crash, retrieving the last saved version of the named file or. if no file is specified, 
typing a list of saved files. The -1 option sets up for editing LIS?, setting the showmaxh and 
lisp options. The —w option sets the default window size to n, and is useful on dialups to start 
in small windows. The —x option causes ex to prompt for a key. which is used to encrypt and 
decrypt the contents of the file, which should already be encrypted using the same key. see 
crypril). The — R option sets the readonly option at the start, t Name arguments indicate files 
to be edited. An argument of the form + command indicates that the editor should begin by 

Tht ftnmdai support of an ibm Graduate Fellowship and the National Scenes Foundation under tranu 
MCS74-07fru»A03 and MC57S-07291 is gratefully acknowledged, 
t Brackets T *1* surround optional parameters here, 
a Not available in all v2 editors due to memory constraints. 
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executing the specified command. If command is omitted, then it defaults to “S’*, positioning 
the editor at the last line of the first file initially. Other useful commands here are scanning 
patterns of the form “/pat" or fine numbers, e.g. “+100" starting at line 100. 

2. Tile manipulation 

2.1. Current file 

Ex is normally editing the contents of a single file; whose name is recorded in the current 
file name. Ex performs all editing actions in a buffer (actually a temporary file) into which the 
text of the file is initially read. Changes made to the buffer have no effect on the file being 
edited unless and until the buffer contents are written out to the file with a write command. 
After the buffer contents are written, the previous contents of the written file are no longer 
accessible. When a file is edited, its name becomes the current file name, and its contents are 
read into the buffer. 

The current file is almost always considered to be edited. This means that the contents of 
the buffer are logically connected with the current file name, so that writing the current buffer 
contents onto that file, even if it exists, is a reasonable action. If the current file is not edited 
then ex will not normally write on it if it already exists.* 

2*2. Alternate file 

Each time a new value is given to the current file name, the previous current file name is 
saved as the alternate file name. Similarly if a file is mentioned but does not become the 
current file, it is saved as the al t e rna t e file n a m e. 

2J. Filename expansion 

Filenames within the editor may be specified using the normal shell expansion conven¬ 
tions. In addition, the character *%’ in filenames is replaced by the current file name and the 
dzanaex by the alternate file name.f 

2.4. Multiple files and named buffers 

If more than one file is given on the command line, then the first file is edited as 
described above. The remaining arguments are placed with the first file in the argument list. 
The current argument list may be displayed with the args command. The next file in the argu¬ 
ment list may be edited with the next command. The argument list may also be resperified by 
specifying a list of names to the next command. These names are expanded, the resulting list 
of names becomes the new argument list, and ex edits the first file on the list. 

For saving blocks of text while editing, and especially when editing more than one file, ex 
has a group of named buffers. These are similar to the normal buffer, except that only a lim¬ 
ited number of operations are available on them. The buffers have names a through nt 

2-5. Read only 

It is possible to use ex in read only mode to look at files that you have no intention of 
modifying. This mode protects you from accidently overwriting the file. Read only mode is on 
when the readonly option is set. It cm be turned on with the — R command line option, by the 
view command line invocation, or by setting the readonly option. It can be cleared by setting 
noreadonly. It is possible to write, even while in read only mode, by indicating that you really 

* Tbs command will say “(Not edited 1“ if (Its current fils is not considered edited, 
y T >n. ntaJces it easy to *1—1 alternately widt two files sod eliminates die need for retyping (be name suopiied 
on an edit co mma nd after a «Vo wrtrt vner last dtaitft diagnostic is received. 

a It is also posable to refer to A through Z the upper sue buffers are the same as the lower bux commands 
append to named buffers rather than replacing if upper case names are used. 
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know what you ire doing. You can write to a different file, or can use the ! form of write, even 
while in read only mode. 

3. Exceptional Conditions 

3.1. Errors and interrupts 

When errors occur ex (optionally) rings the terminal bell and. in any case, prints an error 
diagnostic If the primary input is from a file, editor processing will terminate If an interrupt 
signal is received, ex prints ‘‘Interrupt’* and returns to its command level. If the primary input 
is a file, then ex will exit when this occurs. 

3 JL Recovering from hangups and crashes 

If a hangup signal is received and the buffer has been modified since it was last written 
out. or if the system crashes, either the editor (in the first case) or the system (after it reboots 
in the second) will attempt to preserve the buffer. The next time you log in you should be able 
to recover the work you were doing, losing at most a few lines of changes from the last point 
before the hangup or editor crash. To recover a file you can use the -r option. If you were 
editing the file resume, then you should change to the directory where you were when the crash 
occurred, giving the command 

ex —r resume 

After checking that the retrieved file is indeed ok. you can wnte it over the previous contents of 
that file 

You will normally get mail from the system telling you when a file has been saved after a 
crash. The command 

ex —r 

will print a list of the files which have been saved for you. (In the case of a hangup, the file 
win not appear in the list, although it can be recovered.) 

4. Editing modes 

Ex has five di sti n« modes. The primary mode is command mode. Commands are entered 
in command mode when a prompt is present, and are executed each time a complete line is 
sent. In text input mode ex gathers input lines and places them in the file. The append, insert. 
and chant* g^mand* use text input mode. No prompt is printed when you are in text input 
mode. This mode is left by typing a *.’ alone at the beginning of a line, and command mode 
re sum es. 

The last three modes are open and visual modes, entered by the commands of the same 
u une, and, within open and visual modes text insertion mode. Open and visual modes allow 
local editing operations to be performed on the text in the file. The open command displays 
one at a time on any terminal while visual works on CRT terminals with random positioning 
cursors. »«™g the screen as a (single) window for file editing changes. These modes are 
described (only) in An Introduction to Display Editing with Vi. 

5. Command structure 

Most command names are English words, and initial prefixes of the words are acceptable 
abbreviations. The ambiguity of abbreviations is resolved in favor of the more commonly used 
commands.* 

* Aj in example. (He command sutotmm can be abbreviated ‘S' while the shortest available abbreviation rot 
the irr command is *se\ 
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5 1. Command parameters 

Most commends accept prrt* addresses spedfyto to lines in the Me upon which they 

- «* while ‘‘delete 5" wil. 

delete five lines from the buffer, starting with the current line. 

Some, commands take other information or parameters, this information always being 
given after the command name.* 

5JL Command variants 

a number of commands have two distinct variants. The variant form of the command is 
invoked by placing an T immediately after the command name. Some of the detault variants 
SJ“cwiSw br options; in this case, the T serves to toggle the default. 

5 J. Flags after commands 

ts*» characters **’ ‘o’ and T may be placed after many commands." In this case, the 

command abbreviated by these characters is executed after the command completes. Since ex 
command in ^ ^ g^ge, ‘p’ is rarely necessary.. Any number of 

If toy toe*. <he rprttod offset is 

applied 10 iht current line value before the printing command is executed. 

5 4. Comments 

It is. possible to give editor commands which are iptored. This is useful when making 
enmolia ectitor scripts for which comments ire desired. The comment character is the double 
22?^ aLv command line beginning with * is ignored. Comments beginning wuh may also 

«nSr«=h< in cans where they could be contort as par, of 

text (shell escapes and the substitute and map commands). 

5 J. Multiple commands per line 

More than one command may be placed on a line by separating each pair ot^mrands by 
a f character. However the global commands, comments, and the shell escape . must be the 
last command on a line, as they are not ter minate d by a T- 

5.6. Reporting large changes 

Mo* commands which chan.e to cottons of to editor rtJcf li v. r«d» j* * <* 
of the change exceeds a threshold given by the report option. This feedback helps to detect 
wdLrably large changes so that they may be quickly and easily reversed snth 
' 1^ 'rt* more Ilobal effect such as <bM or «n>l you «tU to mi ormrt tf to net 
chanje in the number of lines in the buffer durini this command esceeds tins threshold. 

4. Command addressing 
6.1. Addressing primitives 

The current line. Most commands leave the current Ime as the last line 
which they affect. The default address for most commands is the current 
line, thus V is rarely used alone as an address. 


i nisrr;». --y-- * 

retuar *xpress»on in a suesiimtt command, or a unsi ***» tor » wor command, ue. l.i copy S’. 

“A ’o’ or T musi * preceded by a blanK or »0 extern in die »npe joecai ease do 
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n 


The ntii line in the editor's buffer, lines being numbered sequentially 
from 1. 


S 

* 

—a 


The last line in the buffer. 

An abbreviation for “l.S", the entire buffer. 
An offset relative to the cunent buffer line.? 


/pat/ ?pc/? 


Scan forward and backward respectively for a line containing pat, a regu¬ 
lar expression (as defined below). The scans normally wrap around the 
end of the buffer. If all that is desired is to prim the next line containing 
pat, then the trailing / or ? may be omitted. If per is omitted or expli¬ 
citly empty, then the last regular expression specified is located.; 


Before each non-relative motion of the current line the previous 
current line is marked with a tag, subsequently referred to as This 
makes it easy to refer or return to this previous context. Marks may 
also be established by the mark command, using single lower case 
letters x and the marked lines referred to as ‘V. 


4.2. Combining addressing primitives 

Addresses to commands consist of a series of addressing primitives, separated by V or V. 
Such address lists are evaluated left-to-right When addresses are separated by V the current 
line V is set to the value of the previous addressing expression before the next address is inter¬ 
preted. If more addresses are given than the command requires, then all but the last one or 
two are ignored. If the command takes two addresses, the first addressed line must precede the 
second in the buffer.? 

7. Command descriptions 

The following form is a prototype for all er commands: 
address command / parameters taunt flags 

All parts are optional: the degenerate ease is the empty command which prints the next line in 
the file. For sanity with use from within visual mode, ex ignores a preceding any com- 
mani 

In the following command descriptions, the default addresses are shown in parentheses, 
which are not. however, part of the co mma nd. 

abbreviate word rhs abbn ab 

Add the named abbreviation to the current list. When in input mode in visual, if word is 
typed as a complete word, it will be changed to rhs. 

(.) append - abbn a 


text 


Reads the input text and places it after the specified line. After the command. V 
addresses the last line input or the specified line if no lines were input. If address 'O' is 
given, text is placed at the beginning of the buffer. 


T The forms \+J* >3* and ire ill equivalent: if the current line is line 100 they all address line 

103. 

t The forms \/ tnd \? san usinf the last refular expression used in i son: after a substitute // and ?? 
would scan usinf the substitute's re«ular expression. 

t Null address specifications are p e rmi tted in a list of addresses, the default in this case is the current line W 
thus MOO* is equivalent to *..100*. It is an error to five a prefix address to a command which expects none. 
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a! 

text 

• 

The variant flag to append toggles the setting for the autoindent option during the input of 
text 

args 

The members of the argument list are primed, with the current argument delimited by T 
and T. 

(...) change count *bbr c 

text 
• 

Replaces the specified lines with the input text The current line becomes the last line 
input; if no lines were input it is left as for a delete. 

cl 

text 

• 

The variant toggles autoindent during the dtanft. 

(.,.) copy addrfiafs abbr: c» 

A copy of the specified lined is placed after aide, which may be ‘O’. The current line V 
addresses the last line of the copy. The command t is a synonym for copy. 

(...) delete buffer count fieps *bbr d 

Remove the specified lines from the buffer. The line after the last line deleted becomes 
the current line; if the lines deleted were originally at the end. the new last line becomes 
the current line. If a named buffbr is specified by giving a letter, then the specified lines 
are saved in that buffer, or appended to it if an upper case letter is used. 

edit file »*>bn e 

txfile 

Used to begin an editing session on a new file. The editor first checks to see if the buffer 
has been modified since the last write command was issued. If it has been, a warning is 
issued and the command is aborted. The command otherwise deletes the entire contents 
of the editor buffer, makes the named file the current file and prints the new filename. 
After insuring that thi< file is sensiblef the editor reads thfe file into its buffer. 

If the read of the file completes without error, the oumber of lines and characters read is 
typed. If there were any non-ASCII characters in the file they are stripped of their non- 
ASCll high bits, and any null characters in the file are discarded. If none of these errors 
occurred, the file is considered edited. If the lact line of the input file is missing the trail¬ 
ing newline character, it will be supplied and a complaint will be issued. This command 
leaves the current line V at the last line read, a 


r Lt. Out it u not a binary Sle ruca as a directory, a Mode or eiiaracer jpecai Me other than tdrnm. a ter¬ 
minal. or a binary or executable Me <as indiated by die first wontl. 
t if executed from within op*n or wsm 4 tfle current line is initially die first line of the Me. 
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el file 

The variant form suppresses the complaint about modifications having been made and not 
written from the editor buffer, thus discarding all changes which have been made before 
editing the new file. 

e +nfile 

Causes the editor to begin at line n rather than at the last line: n may also be an editor 
command containing no spaces, e.g.: “+/pat”. 

file abbri f 

Prints the current file name, whether it has been ‘ (Modified! * since the last write com¬ 
mand, whether it is read only, the current line, the number of lines in the buffer, and the 
percentage of the way through the buffer of the current line.* 

Bit file 

The current file name is changed to file which is considered '(Not edited!'. 

( 1 , S ) global /pat/ emds abbn g 

First marks each line among those specified which matches the given regular expression. 
Then the given co mm and list is executed with initially set to each marked line. 

The command list consists of the remaining commands on the current input line and may 
continue to multiple lines by ending all but the last such line with a A*. If emds (and pos¬ 
sibly the trailing / delimiter) is omitted, each line matching par is printed. Append, insert. 
and change commands and associated input are permitted: the V terminating input may 
be omitted if it would be on the last line of the command list. Open and visual commands 
are permitted in the command list and take input from the terminal. 

The global command itself may not appear in emds. The undo command is also not per¬ 
mitted there, as undo instead can be used to reverse the entire global command. The 
options autoprint and autoindent are inhibited during a global (and possibly the trailing / 
delimiter) and the value of the report option is temporarily infinite, in deference to a 
report for the entire.global. Finally, the context mark is set to the value ofbefore 
the global command begins and is not changed during a global command, except perhaps 
by an open or visual within the globaL 

g! I pad emds abbn ▼ 

The variant form of global runs emds at each line not matching pat. 

(.) insert abbn i 

text 


Places the given text before the specified line. The current line is left at the last line 
input; if there were none input it is left at the line before the addressed line. This com¬ 
mand differs from append only in the placement of text. 


• la the rare case dial the current Sle is '(Not edited I* tins is noted also: in ibis case you have to use the 
form w! to write to the file, sines the editor is not sure that a write will not destroy a file unrelated to the 
c ur r en t comenu of the bufifer. 
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U 

text 

The variant toggles autoindent during the insert. 


(., .+1 ) join count flags “ on * 

Places the text from a specified range of lines together on one line. White space is 
adjusted at each junction to provide at least one blank character, two if there was a \ at 
the end of the line, or none if the first following character is a *)’. If there is already 
white s pace at the end of the line, then thr white space a the start of the next fine will be 

discarded. 


The variant '-*"*<** a simpler join with no white space pro cessin g; the ch ara c t ers in the 
ijrt»* are simply conca t e n ated. 

(.)hx 

The k command is a synonym for mark. It does not require a blank or tab before the fol¬ 
lowing letter. 

(.,.) list count flags 

Prints the specified lines in a more unambiguous way: tabs are printed as *T and the end 
of ~ mr + l line is marked with a trailing *S*. The current line is left at the last line printed. 


map Ihs rhs 

The map command is used to define macros for use in visual mode. Lhs should be a sin¬ 
gle character, or the sequence “*n’\ for n a digit, referring to funcaon key n. When this 
changes or funcaon key is typed in visual mode, it will be as though the corresponding 
rhs had been typed. On terminals without funcaon keys, you can type “#n’\ See secuon 
6.9 of the “Introducaon to Display Editing with Vi” for more details. 

(.) mark x 

Gives the specified line mark x, a single lower case letter. The x must be preceded by a 
blank or a tab. The addressing form *'x’ then addresses this line. The current line is not 
affeced by this command. 

(...) move addr m 

The move command repositions the specified lines to be after addr. The first of the 
moved lines becomes the current line. 


next 


abbr. n 

The next file from the command line argument list is edited. 


The variant suppresses warnings about the mo dificati ons to the buffer not having been 
written out. discarding (irretrievably) any changes which may have been made. 


n fllelist 

n + command fllelist 
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The specified filelist is expanded and the resulting list replaces the current argument list: 
the first file in the new list is then edited. If command is given (it must contain no 
spaces), then it is executed after editing the first such file. 

(...) number count flags abbr. # or nu 

Prints each specified line preceded by its buffer line number. The current line is left at 
the last line printed. 

(.) open flags abbr o 

(.) open /par/ flags 

Enters intraline editing open mode at each addressed line. If pat is given, then the cursor 
will be placed initially at the beginning of the string matched by the pattern. To exit this 
mode use Q. See An Introduction to Display Editing with Vi for more details. 


preserve 

The current editor buffer is saved as though the system had just crashed. This command 
is for use only in emergencies when a write command has resulted in an error and you 
don't know how to save your work. After a preserve you should seek help. 

(...) print count abbr p or P 

Prints the specified lines with non-printing characters printed as control characters ‘* *x’; 
delete (octal 177) is represented as The current line is left at the last line printed. 

(.) put buffer abbr. pu 

Puts b«gk previously deleted or yanked lines. Normally used with delete to effect move¬ 
ment of lines, or with yank to effect duplication of lines. If no buffer is specified, then the 
last deleted or yanked text is restored.* By using a named buffer, text may be restored that 
was saved there at any previous time. 

quit abbr q 

C a 'i sf5 ex to terminate. No automatic write of the editor buffer to a file is performed. 
However, ex issues a warning message if the file has changed since the last write command 
was issued, and does not quit, t Normally, you will wish to save your changes, and you 
should give a write command; if you wish to discard them, use the q! co mm a n d variant. 

q! 

Quits from the editor, discarding changes to the buffer without complaint. 

(.)re*d file abbr: r 

Places a copy of the text of the given file in the editing buffer after the specified line. If 
no file is given the cunent file oame is used. The current file name is not changed unless 
there is none in which case file becomes the current name. The sensibility restricuons for 
the edit command apply here also. If the file buffer is empty and there is no current name 
then ex treats this as an edit command. 


: Not available in all v2 editors due to memory constraints. 

• But no modifyini commands may intervene between the deiett or yank and the put nor may lines be 
moved between hies without usinf a named buder. 
r Lx will also issue a diagnostic if there are more files in the argument list. 
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Address *0’ is legal for this command and causes the file to be read at the beginning of 
the boffer. Statistics are given as for the edit command when the read successfully ter¬ 
minates. After a read the current line is the last line read.* 


( .) read !command 

Reads the output of the command command into the buffer after the specified line. This 
is not a variant form of the comm an d, rather a read specifying a command rather than a 
filename: a blank or tab before the ! is mandatory. 


recover file 

Recovers file from the system save area. Used after a accidental hangup of the phone" 
or a system crash" or preserve command. Except when you use preserve you will be 
notified by mail when a file is saved. 


rewind 

The argument list is rewound, and the first file in the 


ah bn rew 
list is edited. 


rew! 

Rewinds the argument list discarding any changes made to the current buffer. 


set parameter 

With no arguments, prints those options whose values have been changed from their 
fanitr; with parameter all it prints all of the option values. 

Giving an option, name followed by a 'V causes the current value of that option to be 
printed. The 'V is unnecessary unless the option is Boolean valued. Boolean options are 
given values either by the form ‘set option'- to turn them on or ‘set adoption’ to cum them 
off; string and numeric options are as sign ed via the form ‘set opr/o/r*value . 

More than one parameter may be given to set\ they are interpreted left-to-rigbi. 


shell 


abbn sh 


A new shell is created. When it terminates, editing resumes. 


source file aoon 50 

Reads and executes commands from the specified file Source commands may be nested. 

(...) substitute Ipatlrepll options count fia^s abbr s 

On each specified line, the first instance of pattern pat is replaced by replacement pattern 
repl. If the global indicator option character ‘g’ appears, then all instances are substituted; 
if the confirm indication character ‘c’ appears, then before each substitution the line to be 
substituted is typed with the string to be substituted marked with T characters. By typing 
an *y* one can cause the substitution to be performed, any other input causes no change 
to take place. After a substitute the current line is the last line substituted. 

Lines may be split by substituting new-line characters into them. The newline in repi 
must be escaped by preceding it with a *\\ Other metacharacters available in pat and repi 
are described below. 


: Within open ana visual the current line is set to the first line read rather than the last. 

— The system saves a copy of the file you were ediunt only if you have maae changes to the file. 
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stop 

Suspends the editor, returning control to the top level shell. If autowrtte is set and there 
are unsaved changes, a write is done first unless the form stop! is used. This commands 
is only available where supported by the teletype driver and operating system. 

(...) substitute options count flats abbn s 

If pat and rtpi are omitted, then the last substitution is rep eated . This is a synonym for 
the ft command. 

(...) t addr flags 

The t command is a synonym for copy. 
ta tat 

The focus of editing switches to the .location of tag. switching to a different line in the 
current file where it is denned, or if necessary to another file.* 

The tags file is normally created by a pr ogr a m such as ctags. and consists of a number of 
lines with three fields separated by blanks or tabs. The first field gives the name of the 
tag. the second the name of the file where the tag resides, and the third gives an address¬ 
ing form which can be used by the editor to find the tag; this field is usually a contextual 
yan using '/patT to be immune to minor changes in the file. Such scans are always per¬ 
formed as if nomagic was set. 

The tag names in the tags file must be sorted alphabetically. * 

unabbreviate word abbn ana 

Delete word from the list of abbreviations. 

undo abbn a 

Reverses the change made in the buffer by the last buffer editing command. Note that 
global commands are considered a single command for the purpose of undo (as are open 
and vis ua l. J Also, the commands write and edit which interact with the file system cannot 
be undone. Undo is its own inverse. 

Undo always marks the previous value of the current line V as *"\ After an undo the 
current line is the first line restored or the line before the first line deleted if no lines 
were restored. For commands with more global effect such as global and visual the 
current line regains it’s pre-command value after an undo. 

unmap Ihs 

The macro expansion associated by map for Ihs is removed. 

(1 , S ) ▼ /pat/ ands 

A synonym for the global command variant g!, running the specified cmds on each line 
which does not match pat 

version abbn ve 

Prints the current version number of the editor as well as the date the editor was last 
changed. 


* IT you have modified the current file before pving a tar command, you must *nte it ouu pving mower 
i at command, specifying no tat will reuse the previous tag. 
s Not available in all v 2 sditors due to memory constraints. 
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(.) visual type count flats ibbr vi 

Enters visual mode at the specified line. Type is optional and may be ’ . *f * or V as in 
the z command to specify the placement of the specified line on the screen. By default, if 
type is omitted, the specified line is placed as the first on the screen. A count specifies an 
initial window size; the default is the value of the option window. See the document An 
Introduction to Display Editing with Vi for more details. To exit this mode, type Q. 

visual file 
visual + n file 

From visual mode, this command is the same as edit. 

( 1 . S ) write abbn w 

Writes made back to file, printing the number of lines and characters written. 

Normally file is omitted and the text goes back where it came from. If a file is specified, 
then text will be written to that file.* If the file does not exist it is created. The current 
file name is changed only if there is no current file name; the current line is never 
changed. 

If an error occurs while writing the current and edited file, the editor considers that there 
has been “No write since last change’* even if the buffer had not previously been 
modified. 

( 1 . S ) write>> file abbnw>>- 

Writes the buffer contents at the end of an existing file. 

w! name 

Overrides the checking of the normal write command, and will write to any file which the 
system permits. 

( 1 , S ) w '.command • 

Writes the specified lines into command. Note the difference between w! which overrides 
checks and w ! which writes to a command. 

wq name 

Like a write and then a quit command, 
wq! name 

The variant overrides checking on the sensibility of the write command, as w! does, 
xit name 

If any changes have been made and not written, writes the buffer out. Then, in any case, 
quits. 

(...) yank buffer count abbr. ya 

Places the specified lines in the named buffer, for later retrieval via put. If no buffer name 
is specified, the lines go to a more volatile piace; see the put command description. 


* The editor wmes to a nie only if it is the current file and is if the file does not exist, or if the file is 
actually a teletype. Ideyiny, IdrumiiL Otherwise, you must pve the variant form wj to force the write. 
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(. + 1)2 count 

Print the next count lines, default window. 

(.) i type count 

Pnms a window of text with the specified line at the top. If type is *—* the line is placed 
at the bottom; a V causes the line to be placed in the center.* A count gives the number 
of lines to be displayed rather than double the number specified by the scroll option. On a 
CRT the screen is cleared before display begins unless a count which is less than the 
screen si 2 e is given. The current line is left at the last line printed. 

! command 

The remainder of the line after the *!’ character is sent to a shell to be executed. Within 
the text of command the characters and *#’ are expanded as in filenames and the char¬ 
acter *!’ is replaced with the text of the previous command. Thus, in particular. *!!* 
repeats the last such shell escape. If any such expansion is performed, the expanded line 
will be echoed. The current line is unchanged by this command. 

If there has been “(No write]'* of the buffer contents since the last change to the editing 
buffer, then a diagnostic will be printed before the command is executed as a warning. A 
single T is printed when the command completes. 

( addr , addr ) ! command 

Takes the specified address range and supplies it as standard input to command the result¬ 
ing output then replaces the input lines. 

(S) - 

Prints the line number of the addressed line. The current line is unchanged. 

(...) > count flags 
(...) < count flags 

Perform intelligent shifting on the specified lines; < shifts left and > shift right. The 
quantity of shift is determined by the shiftwidth option and the repetition of the 
specification character. Only white space (blanks and tabs) is shifted; no non-white char¬ 
acters are discarded in a left-shift. The current line becomes the last line which changed 
due to the shifting. 

*D 

An end-of-file from a terminal input scrolls through the file. The scroll option specifies 
the size of the scroll, normally a half screen of text. 

(.+1 , .+ 1 ) 

(.+1 ,. + l)| 

.An address alone causes the addressed lines to be printed. A blank line prints the next 
line in the file. 


* Forms % z~* and *zf* ilso exist: *z«' pieces ifte current line in the caster, surrounds it with lines of * 
characters and leaves the current line at this line. The form *zf prints the window before ‘Z-* would. The 
euraaers *•’. and ’ may be repeated for cumulative etfecL On some v2 editors, no type may be 
jrven. 
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( . . .) k options count flags 

Repeats the previous substitute command. 

options count flags 

Replaces the previous regular expression with the previous replacement pattern from a 
substitution. 

8. Regular expressions and substitute replacement patterns 

8.1. Regular expressions 

A regular expression specifies a set of strings of characters. A member of this set of 
strings is said to be matched by the regular expression. Ex remembers two previous regular 
expressions; the previous regular expression used in a. substitute command and the previous reg¬ 
ular expression used elsewhere (referred to as the previous scanning regular expression.) The 
previous regular expression can always be referred to by a null re. e.g. 7/’ or *??\ 

8.2. Magic and nomagie 

The regular expressions allowed by ex are constructed in one of two ways depending on 
the setting of the magic option. The ex and w default setting of magic gives quick access to a 
powerful set of regular expression metacharacters. The disadvantage of magic is that the user 
must remember that these metacharacters are magic and precede them with the character V to 
use them as “ordinary” characters. With nomagic, the default for edit, regular expressions are 
much simpler, there being only two metacharacters. The power of the other me t a ch a ra cters is 
still available by preceding the (now) ordinary character with a *\\ Note that ‘V is thus always 
a metacharacter. 

The remainder of the discussion of regular expressions assumes that that the setting of 
this option is magic, t 

8_3. Basic regular expression summary 

The following basic constructs are used to construct magic mode regular expressions. 

char An ordinary character matches itself. The characters T at the beginning of a 

line, 'V at the end of line. as any character other than the fint, V. ‘(\ 
and are not ordinary characters and must be escaped (preceded) by Y to be 
treated as such. 

| At the beginning of a pattern forces the match to succeed only at the begin¬ 

ning of a line. 

$ At the end of a regular expression forces the match to succeed only at the end 

of the line. 

. Matches any single character except the new-line character. 

\< Forces the match to occur only at the beginning of a “variable” or “word”; 

that is. either at the beginning of a line, or just before a letter, digit, or under¬ 
line and after a character not one of these. 

\> Similar to '\<\ but matching the end of a “variable” or “word”. Le. either 

the end of the line or before charamer.which is neither a letter, nor a digit, nor 
the underline character. * 


T To discern wioi is true with nomatK it suffices to remember that the only special characters m this case *iil 
be •*’ at the beginmna of a regular expression. 1* at the end of a regular expression, and V. 'With oomoeic 
the characters and also lose their specal meanings related to the replacement pattern of a substitute. 
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Ism/rgJ Matches any (single) character in the dass denned by string. Most characters 

in string define themselves. A pair of characters separated by ' in string 

defines the set of characters collating between the specified lower and upper 
bounds, thus ‘la—zP as a regular expression matches any (single) lower-case 
letter. If the first character of string is an *1* then the construct matches those 
characters which it otherwise would not; thus *(Ia—z]* matches anything but a 
lower-case letter (and of course a newline). To place any of the characters T. 
*(*, or *— * in string you must escape them with a pre cedin g V. 

8.4. Combining regular expression primitives 

The concatenation of two regular expressions matches the leftmost and then longest string 
which can be divided with the first piece matching the first regular expression and the second 
piece matching the second. Any of the (single character matching) regular expressions men¬ 
tioned above may be followed by the character “* to form a regular expression which matches 
any number of adjacent occurrences (including 0) of characters matched by the regular expres¬ 
sion it follows. 

The character may be used in a regular expression, and matches the text which defined 
the replacement part of the last substitute command. A regular expression may be enclosed 
between the sequences ‘\0 and *\)* with side effects in the substitute replacement patterns. 

8_5. Substitute replacement patterns 

The basic metacharacters for the replacement pattern are *4 and * ; these are given as 
*\4‘ and V* when nomagic is set. Each instance of ‘4’ is replaced by the characters which the 
regular expression matched. The metacharacter stands, in the replacement pattern, for the 
defining text of the- previous replacement partem. 

Other metasequences possible in the replacement pattern are always introduced by the 
escaping character ‘V. The sequence V is replaced by the text matched by the /i-th regular 
subexpression enclosed between ‘\C and *\)\t The sequences *\u* and *\T cause the unmedi- 
aieiy following character in the replacement to be convened to upper- or lower-case respectively 
if this character is a letter. The sequences ‘\IT and 4 \L’ turn such conversion on, either until 
»\£* or *\ e ’ js encountered, or until the end of the replacement pattern. 

9. Option descriptions 

autoindent, ai default: noai 

Can be u sH to ease the preparation of structured program text. At the beginning of each 
append, change or insert command or when a new line is opened or created by an append, 
change, insert, or substitute operation within open or visual mode, ex looks at the line being 
appended after, the first line changed or the line inserted before and calculates the 
amount of white space at the start of the line. It then aligns the cursor at the level of 
indentation so determined. 

If the user then types lines of text in. they will continue to be justified at the displayed 
indenting level. If more white space is typed at the beginning of a line, the following line 
will start aligned with the first non-white character of the previous line. To back the cur¬ 
sor up to the preceding tab stop one can hit *D. The tab stops going backwards are 
defined at multiples of the shiftwidth option. You cannot backspace over the indent, 
except by sending an end-of-Sle with a 


♦ When nested, parenthesized su Degressions ire present, n 
sunmi from the left. 


is determined by countm* occurrences of *\(’ 
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Specially processed in this mode is a line with no characters added to it. which turns into a 
completely blank line (the white space provided for the automdent is discarded.) Also spe- 
dally processed in this mode are lines beginning with an T and immediately followed by 
a *D. This causes the input to be repositioned at the beginning of the line, but retaining 
the previous indent for the next line. Similarly, a '0* followed by a *D repositions at the 
beginning but without retaining the previous indent. 

Autoindent doesn’t happen in global commands or when the input is not a terminal. 

autoprint, ap default: ap 

Causes the current line to be printed- after each delete, copy, join, move, substitute, t, undo 
or shift command. This has the same effect as supplying a trailing ‘p’ to each such com* 
manci. Autoprint is suppressed in globais. and only applies to the last of many commands 
on a line. . 

autowrite, aw default: noaw 

the contents of the buffer to be written to the current file if you have modified it 
and give a next, remind, stop, tag, or / command, or a *f (switch files) or ‘1 (tag goto) 
command in vtsuaL Note, that the edit and ex commands do not autowrite. In each case, 
there is an equivalent way of switching when autowrite is set to avoid the autowrite (edit 
for next, rewind! for .1 rewind , stop! for stop, tag! for tag, shell for /. and :e # and i :ta 1 
command from within visual). 

beautify, bf default: nobeautify 

Causes all control characters except tab, newline and form-feed to be discarded from the 
input. A complaint is registered the first time a backspace character is discarded. Beautify 
does not apply to command input. 

directory, dir default: dirWtmp 

Specifies the directory in which cr places its buffer file. If this directory in not writable, 
then the editor will exit abruptly when it fails to be able to create its buffer there. 

edcompatible default: noedcompatibie 

Causes the presence of absence of g and c suffixes on substitute commands to be remem¬ 
bered. and to be toggled by repeating the suffices. The suffix r makes the substitution be 
as in the ~ command, instead of like <L « 

errorbeils, eb default: noeb 

Error messages are preceded by a belL* If possible the editor always places the error mes¬ 
sage in a standout mode of the terminal (such as inverse video) instead of ringing tbs 
belL . . 

hardtabs, bt default: hi*"8 

Gives the boundaries on which terminal hardware tabs are set (or on which the system 
expands tabs). 

igsorecase, ic default: noic 


a Version 3 only. 

* Beil rinyjny in ootn and *isuai on errors is not suppressed by setuny n orb. 
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All upper case characters in the text are mapped to lower case in regular expression 
matching. In addition, all upper case characters in regular expressions are mapped to 
lower case except in character class specifications. 

lisp default: nolisp 

Autoindent indents appropriately for lisp code, and the ( ) ( } II and 11 commands in open 

and visual are modified to have meaning for lisp. 

list default: noiist 

All printed lines will be displayed (more) unambiguously, showing tabs and end-of-lines 
as in the list command. 

magic default: magic for ex and Wf 

If nomagic is set, the number of regular expression metacharacters is greatly reduced, with 
only ‘I’ and ‘S' having special effects. In addition the metacharacters '** and '<&’ of the 
replacement pattern are treated as normal characters. All the normal metacharacters may 
be made magic when nomagic is set by preceding them with a V. 

mesg default: mesg 

Causes write permission to be turned off to the terminal while you are in visual mode, if 
nomesg is set. tt 

number, nn default: nonumber 

Causes all output lines to be printed with their line numbers. In addition each input line 
will be prompted for by supplying the line number it will have. 

.open default: open 

If noopen , the commands open and visual are not permitted. This is set for edit to prevent 
confusion resulting from accidental entry to open or visual mode. 

optimize, opt default: optimize 

Throughput of text is expedited by setting the terminal to not do automatic carriage 
returns when printing more than one (logical) line of output, greatly speeding output on 
terminals without addressable cursors when text with leading white space is printed. 

p a r agra phs, para de f a u lt: para** IPLPPPQPP Libp 

Specifies the paragraphs for the ( and ) operations in open and visual The pairs of charac¬ 

ters in the option's value are the names of the macros which start paragraphs. 

prompt default: prompt 

Command mode input is prompted for with a 

redraw - default: noredraw 

The editor simulates (using great amounts of output), an intelligent terminal on a dumb 
terminal (e.g. during insertions in visual the charaoers to the right of the cursor position 
are refreshed as each input character is typed.) Useful only at very high speed. 


? SomafK for idiL 
« Version 3 only. 
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remap default: remap 

If on, macros are repeatedly tried until they are unchanged, t* For example, if o is 
mapped to 0, and 0 is mapped to I. then if remap is set, o will map to I. but if noremap is 
set, it will map to 0. 

report default: report-5f 

Specifies a threshold for feedback from commands. Any command which modifies more 
than the specified number of lines will provide feedback as to the scope of its changes. 
For commands yigh as global, open, undo, and visual which have potentially more far 
reaching scope, the net ffrawg* in the number of lines in the buffer is presented at the end 
of the co mmand, subject to this same threshold. Thus notification is suppressed during a 
global command on the individual commands performed. 

scro jj default: scroll —Vi window 

Determines the number of logical lines scrolled when an end-of-file is received from a 
terminal input in command mode, and the number of lines printed by a command mode r 
command (double the value of scroll ,). 

sec ij onJ default: sections—SHNHH HU 

Specifies the section macros for the (I and 11 operations in open and visual The pairs of 
characters in the options’s value are the names of the macros which start paragraphs. 


shell, sh default: sh-/bin/sh 

Gives the path name of the shell forked for the shell escape command *!’, and by the shell 
command. The default is taken from SHELL in the environment, if present 

shiftwidth. sw default: sw—8 

Gives the width a software tab stop, used in reverse tabbing with *D when using autom- 
dent to append text, and by the shift commands. 

showmatch. sm default: nosm 

In open and visual mode, when a ) or } is typed, move the cursor to the matching ( or { 
for one second if this matching character is on the screen. Extremely useful with lisp. 

siowopen. slow terminal dependent 

Affects the display algorithm used in visual mode, holding off display updating during 
input of new text to improve throughput when the terminal in use is both slow and unin¬ 
telligent. See An Introduction to Display Editing with Vi for more details. 


tabstop. ts default: ts—8 

The editor expands tabs in the input file to be on tabstop boundaries for the purposes of 
display. 


taglengtfa. tl default: ti-0 

Tags are not significant beyond this many characters. A value of zero (the default) means 
that ail characters are significant. 


t: V^nion j only, 
t 2 for edit. 
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tags default: tags "tags /usr/lib/tags 

A path of files to be used as tag files for the tag command. te A requested tag is searched 
for in the specified files, sequentially. By default (even in version 2) files called tags are 
searched for in the current directory and in /usr/lib (a master file for the entire system.) 

term from environment TERM 

The terminal type of the output device. 

terse default: noterse 

Shorter error diagnostics are produced for the experienced user. 

warn default: warn 

Warn if there has been ‘{No write since last changel’ before a *!’ command escape. 

window default: window—speed dependent 

The number of lines in a text window in the visual command. The default is 8 at slow 
speeds (600 baud or less), 16 at medium speed (1200 baud), and the full screen (minus 
one line) at higher speeds. 

w300, wl2Q0, w9600 

These are not true options but set window only if the speed is slow (300). medium 
(1200), or high (9600), respectively. They are suitable for an EXINTT and make it easy 
to change the 8/16/full screen rule. 

wrapscan, ws default: ws 

Searches using the regular expressions in addressing will wrap around past the end of the 
file. 

wrapraargin, wm default: wm—0 

Defines a margin for automatic wrapover of text during input in open and visual modes. 

See An Introduction to Text Editing with Vi for details. 

writeany, wa default: nowa 

Inhibit the checks normally made before write commands, allowing a write to any file 
which the system protection mechanism will allow. 

10. Limitations 

Editor limits that the user is likely to encounter are as follows: 1024 characters per line. 
256 characters per global command list, 128 characters per file name. 128 characters in the pre¬ 
vious inserted and deleted text in open or visual, 100 characters in a shell escape command. 65 
characters in a siring valued option, and 30 characters in a tag name, and a limit of 250000 lines 
in the file is silently enforced. 

The visual implementation limits the number of macros denned with map to 32. and the 
total number of characters in macros to be less than 512. 

Acknowledgments. Chuck Haley contributed greatly to the early development of ex. Bruce 
Englar encouraged the redesign which led to ex version 1. Bill Joy wrote versions l and 2.0 
through 2.7, and created the framework that users see in the present editor. Mark Horton 
added macros and other features and made the editor work on a large number of terminals and 
Unix systems. 


» Version 3 only. 









Ex changes — Version 3.1 to 3.5 

This update describes the new features and changes which have been made in convening 

from version 3.1 to 3.5 of ex. Each change is marked with the first version where it appeared. 

Update to Ex Reference Manual 

Command Una options 

3.4 A new command called view has been created. View is just like W but it sets readonly. 

3.4 The encryption code from the v7 editor is now part of ex. You can invoke ex with the 
—x option and it will ask for a key, as ed. The ed x command (to enter encryption mode 
from within the editor) is not available. This feature may not be available in ail instances 
of ex due to memory limitations. 

Commands 

3.4 Provisions to handle the new pr oces s stopping features of the Berkeley TTY driver have 
been added. A new command, stop, takes you out of the editor deanly and efficiently, 
returning you to the shell. Resuming the editor puts you back in command or visual 
mode, as appropriate. If autawrite is set and there are outstanding changes, a write is done 
first unless you say “stop!”. 

3.4 A 

,-vi <flle> 

command from visual mode is now treated the same as a 
adit <file> or ax <file> 

command. The meshing of the vi command from a command mode is not affected. 

3 J A new command mode command xd (abbreviated x) has been added. This is the same as 
wq but will not bother to write if there have been no changes to the file. 

Options 

3.4 A read only mode now lets you guarantee you won’t clobber your file by accident. You 
can set the on/off option readonly (ro) t and writes will fail unless you use an ! after the 
write. Commands such as x, ZZ. the autowrite option, and in general anything that writes 
is affected. This option is turned on if you invoke ex with the — R flag. 

3.4 The wrapmarjin option is now usable. The way it works has been completely revamped. 
Now if you go past the margin (even in the middle of a word) the entire word is erased 
and rewritten on the next line. This changes the semantics of the number given to wrap- 
margin. 0 still means off. Any other number is still a distance from the right edge of the 
s c r ee n , but this location is now the right edge of the area where wraps can take place. 
hv^ri of the left edge. Wrapmargin now behaves much like fill/nojusdfy mode in nroff. 

3 j The options w300. w/200, and *9600 can be set. They are synonyms for window, but only 
apply at 300, 1200, or 9600 baud, respectively. Thus you can specify you want a 12 line 
window at 300 baud and a 23 line window at 1200 baud in your EXINTT with 

set W300-12 wl200-23 

3J The new option timeout (default on) causes macros to time out after one second. Turn it 
off and they will wait forever. This is useful if you want multi character macros, but if 
your terminal sends escape sequences for arrow keys, it will be ne ces sa r y to hit escape 
twice to get a beep. 
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3.3 


The new option rtmap (default on) causes the editor to attempt to map the result of a 
mLro mapping again until the mapping fails. This makes .t possible, say, to nup q to - 
and #1 something else and get ql mapped to something else. Turning it off makes it 
possible to map *L to 1 and map *R to *L without having R map to L 
The new (string) valued option mgs allows you to specify a list of tag files, similar to the 
‘‘path'' variable of ah. The files are separated by spaces (which are entered preceded by 
a Wsiash) and are searched left to right. The default value is ‘^ags /usr/lib/ta^ . 
wfakh has ihe same effect as before. It is recommended that nags always be the first 
entry. On Emie CoVax, /usr/lib/tags contains entries for the system defined library pro¬ 
cedures from section 3 of the man ual. 


Environment enquiries 

3.4. The editor now adopts the convention that a null stnsg m jhejnvironment is the same as 


not >w"i"g sec This applies to TERM* TERM CAP. and EXINTT. 


VI Tutorial Update 


Deleted features 

3 3 The “q" command from visual no longer works at alL You must use “0” to get to ex 
command mode. The “q” command was deleted because of user complaints about hitting 

it by accident too often. 

3 5 The provisions for changing the window size with a numeric prefix argument to certain 
visual commands have been deleted. The correct way to change the window size is to use 
the z command, for example z5<cr> to change the window to 5 lines. 

3 j jbe option ’mapinpuf is dead. It has been replaced by a much more powerful mechan¬ 
ism: “snap!”. 


Change in default option settings 

3 J The default window sizes have been changed. At 300 baud the window is now 8 Una (it 

was 1/2 the screen size). At 1200 baud the window is now 16 lines (it was 2/3 the screen 

size, which was usually also 16 for a typical 24 line CRT). At 9600 baud the window * 

still the fufi screen size. Any baud rate less than 1200 behaves like 300, any over 1200 

like 9600. This chang e makes w more usable on a large screen at slow speeds. 


Yi 

3 J The command “ZZ” from vi is the same as “at<cr>”. This is the recommended wy to 
leave the editor. Z must be typed twice to avoid hitring it accid en tly. 

3 4 The command *Z is the same as “:siop<cr>” Note that if you have an arrow key that 
sends *Z the stop function will take priority over the arrow funcrion. If you have your 
“susp” character set to something besides *Z, that key will be honored as well. 

3 j ja Q ow possible from visual to string several search expressions together separated by 
semicolons the same as command mode. For example, you can say 

/foo/v/bar 

from visual and it will move to the first “bar” after the next “foo” This also works 
within one line. 

3 J *R is now the same as *L on terminals where the right arrow key sends *L (This includes 
the Televideo 912/920 and the ADM 31 terminals.) 
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3.4 The visual page motion commands *F and *B now treat any preceding counts as number 
of pages to move, instead of changes to the window size That is. 2~F moves forward 2 
pages. 

Macros 

3 J The “mapinput” mechanism of version 3.1 has been replaced by a more powerful 
mechanism. An “!” can follow the word “map” in the map command. Map Ted macros 
only apply during input mode, while map’ed macros only apply during command mode. 
Using “map” or “map!” by itself produces a listing of macros in the corresponding 
mode 

3.4 A word abbreviation mode is now available. You can define abbreviations with the abbre¬ 
viate command 

abbr foo find outer otter 

which maps “foo” to “find outer otter”. Abbreviations can be turned off with the unab¬ 
breviate command. The syntax of these commands is identical to the map and unmap 
commands, except that the ! forms do not exist. Abbreviations are considered when in 
visual input mode only, and only affect whole words typed in. using the conservative 
H»nnirinn (Thus “foobar” will not be mapped as it would using “map!”) Abbreviate 
and unabbreviate can be abbreviated to “ab” and “una”, respecuvely. 
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NAME 

med — screen editor 
SYNOPSIS 

med file [sfarffine) [searchfcey] 

med * 

med 

DESCRIPTION , ^ 

Med calls the MED editor, which allows you to edit a file using the screen 
of your terminal and the cursor keys, somewhat like paper, pencil and 
eraser. 

If you call the editor by med file, the first lines of the file will be shown on 
the terminal screen. If the file does not exist, it will be created. 

Med called with no arguments continues where the previous med session 
ended. 

Med called with argument "-" restores only one file from the last session. 

The purpose of a screen editor is to create a new file, or to look at and 
change existing files. Med allows you to look through a file by moving a 
•'window” (the text shown at the screen) over the files contents. The win¬ 
dow may be moved up, down, to the left or the right. The "cursor" (a 
blinking underline or box) shows where med is at the moment. Initially 
med is in "replace mode", i.e. the characters typed will replace those 
under the cursor. The cursor may be moved around with the arrow keys 
BSElF1 or With Ireturnl . inomei or ftaE) . 

To change text on the screen, the cursor has to be placed there and the 
new characters entered. Idelcm deletes the character under the cursor. 
To insert characters in the middle of a word (like a ’d’ in ’midle’), press 
[insertl; then new characters will be inserted, and the rest of the line will 
move to the right. Pressing Imserti again, med is switched back to 
"replace mode". . 

"Function keys" are special keys along the top or the right of the key¬ 
board. Each function key does one job, such as moving some lines, look¬ 
ing for a word, or using another file. A picture of all the different func¬ 
tion keys for your terminal should be attached to this description. 

Some functions take arguments such as a number, a search string, a file 
name. etc. To enter an argum ent, type t he sequence: 

I enter | number or string I function! . 

I ent er ) leaves an •©* marker on the screen to remind you where the cur¬ 
sor was. It then goes to the bottom line on the screen to read the argu¬ 
ment. This bottom line is also used to display error messages. 
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Function keys and their meaning 
Move around:_ 


t X - - 

Move cursor 

±tnb 

Skip to next/previous tab stop 

±page 

Move to next/previous page 

±line 

Move a halfpage up/down 

±search 

Search for a word 

goto 

Goto line n 

left 

Move window left 

right 

Move window right 

Use another 1 

lie or window: 

use 

Use another file 

window 

Create/delete a window 

chwin 

Go to next window 


Cut and paste: 


backspace 

Delete character left of cursor 

close 

Delete line(s) into CLOSE buffer 

delch 

Delete character 

open 

Insert blank line(s) 

pick 

Copy text to PICK buffer 

put 

Get text from PICK buffer 

restore 

Get text from CLOSE buffer 


Others: 


do 

Hun a Unix command 

enter 

Enter a parameter 

exit 

Go back to Unix 

insert 

Flip insert mode 

quote 

Control character escape 

refresh 

Refresh 

save 

Write changes to disk 

chtabs 

Change tabs 

macro 

collect keystrokes 


lenterl n Move the cursor n lines/columns in the direction of the 

arrow. 
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ISHadiLLG 


Remove the last character entered; thus typing 

•*E R X {backspace) R*’ is the same as "E R R". This also 

works in insert mode. 


chta F I Set a tab stop at the current position. 

enter! IcHTaFI Remove the tab stop at the current position. 


cftwmi 

enterl n Ichwinl 
lenterl W*~* Ichwml 


Go to the next window. 

Go to window n. Windows are numbered in the order they 
are created. 

Argument defined by the cursor is used as window 
number. 


closel 



Delete one line. It is saved in the CLOSE buffer. 

Delete the rest of the line, replacing it with the line below. 
Delete n lines and save them in the CLOSE buffer. 

Delete lines or a rectangle defined by the cursor and put 
it into the CLOSE buffer. 


Idelch 


Delete the character at the current cursor position, mov¬ 
ing the following characters to the left. 



Run the previous DO command exactly as it was given. 
Take the current line as a command for the shell. Results 
are inserted below the current line. 

crod is a Unix command in the format [n[I]] prg l“*g...J (in 
shell notation). It replaces n paragraphs (or n lines if 1 
appears) by the result of running filter prg on that text 
with given args. The replaced paragraphs are saved in the 
CLOSE buffer. 


[exTQ 

lenterl a iexitl 
lenterl ad lexitj 


Exit mcd, writing back the changed files to disk (a backup 
file named *.bak is created). 

Exit, but do not save files. 

Terminate with core dump. 


gotol 

enter 

leotoj 

enter 

n goto 

enter 

n--» igotoi 


Move window to top of file. 

Move window to end of file. 

Move to the nth line. 

Argument defined by the cursor is used as line number. 


linsertl 


Put the editor into insert mode. Subsequent characters 
are inserted at the cursor, i.e.. characters to the right of 
the cursor are not replaced but moved to the right. 
Pressing flnscTfl again will place rned back to replace 
mode. 
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enterlfleTtl 

enter! nTieitl 



l-Hinei 
n H-linel 


-line 

enter 

|-line 

enter 

n i-line| 


ojgenJ 

enterl fopenl 
enter! n lopenl 
enterl * lopenl 


-t-pagel 


enterl n Kpage 



n l-pagej 


pick | 

enter] n Ipickl 
enterl n*--* [pick] 


Iput-I 

n IhhS_ 

n«—» iputi 


Iquotej 


enter 

enter 


Irelreshl 

I re store] 

I enterl n Irestorel 


Move window left (about a 1/3 window width). 

Make the current column the last one (if possible). 

Move window n columns left. 

Move window down (about 1 /3 page). 

Make the current line the top one. 

Move window down n lines. 

Move window up (about 1/3 page). 

Make the current line the bottom one (if possible). 

Move window up n lines. 

Open up one blank line. 

Split the line exactly at cursor position. 

Open up for n blank lines. 

Insert blank lines or rectangle in area defined by cursor. 

Move window down one page (page = size of window). 

Move down n pages. 

Move window up one page. 

Move up n pages. 

Put the current line into the PICK buffer. 

Put n lines into the PICK buffer. 

Place lines or rectangle defined by cursor in PICK buffer. 

Insert the contents of the PICK buffer (i.e. the lines or 
rectangle last "picked") at the current position. 

Insert n copies of the PICK buffer at the current position. 
Argument defined by the cursor is used as number of 
copies. 

To put a control character into the file. I quote I echoes as 
a ©, and whatever key on the keyboard you press next 
appears as some printable character. The two characters 
now behave as two characters on the screen, but they are 
really the single control character in the file. Changing 
the second letter changes the control character; chang¬ 
ing the preceding mark results in two ordinary charac¬ 
ters. 

Redraw terminal display. 

Insert the contents of the CLOSE buffer (i.e. the lines or 
rectangle last deleted). Insertion is done at the current 
position. 

Insert n copies of the CLOSE buffer at the current posi- 
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lenterl U«- 


tion. 

-» [restore! Argument defined by the cursor is used as number of 
copies. 


right) 

ent erl IrTght I 
enter! n Irightl 


save| 

enterl name [save] 


lenterj U«--» Isave 

KsearcTTI 


Move window right (about a 1/3 window width). 

Make current column the first one. 

Move window right n columns. 

Save the file shown in the current window. 

Save the file shown in the current window under filename 
name. 

Argument defined by the cursor is used as filename. 

Search forwards (from the cursor towards the end of the 
file) for an occurrence of the search key lost used. 

Search key used is from cursor position up to next blank. 


enterl H-searchj 
'enter] word Ksearchi Search for the next occurrence of word. 


en t,erl U*--» Usearchj Argument defined by the cursor is used as search key. 


1-search] 


enterl [-search] 


Search backwards (from the cursor towards the beginning 
of the file) for on occurrence of the search key last used. 
Search key used is from cursor position up to next blank. 


enter] word i-searchl Search for the next occurrence of word 


enterl U« 


j-searcni ocarcn lur uic ucai utuuncuuc vi ww*u. 

1-searchl Argument defined by the cursor is used as search key. 



lenterl name lusej 


lenterl U*--* [use 


Switch to the file previously used. 

Edit file, taking its name from cursor position up to next 
blank. 

Make the current window look at file name. A linenumber 
and/or searchkey can be specified (as in the med com¬ 
mand). 

Argument defined by the cursor is used as filename. 


[window! 


Make another window on the real screen, so that you now 
have two, or three, or more windows. A " defau lt file" is 
used. It may be set to look at a file using |use| . and all 
other functions work within this little window. If the cur¬ 
sor is on the first or last column of your window the line 
separating the two windows goes horizontally on the line 
where the cursor is. The separating line goes vertically if 
the cursor is on the first or last line of your window. You 
may have two windows looking at the same file. 'In fact, it 
is rather neat, since changes made by editing in either 
window are reflected (at reasonable intervals) in the 
other window. 

Delete last created window and return to the previous 
one. 

lente r] name |window| Create another window displaying file name. 


|enter|[window| 
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MACRO 

Typing_ 

Imacrol keystrokes Imacrol key 

stores the keystrokes sequence into the key. To avoid trouble, key can 
only be a printable character. From now on pressing the key is 
equivalent to typing the (long) keystrokes sequence. The sequence 
Imacrol Imacrol key 

restores the original function of the key. 

Miscellaneous 

What do the funny characters in the margins mean? 

| is normal. 

; means this is past the end of the file. You may still type stuff - 
there just wasn’t anything there before. Even if you type some¬ 
thing on a line, the character won’t go away until the line is rewrit¬ 
ten by the editor - but the stuff is still there. 

< There is still more text to the left (may be blanks). 

> There is still more text to the right (not only blanks). 

When editing a file for which you don’t have write permission, the 
appropriate editor functions will be disabled. 

What to do when disaster comes: 

You are protected from loss of. files by the insurance system of the MED 
editor. If you edit a file named foo, the old file foo is renamed foo.bak 
(the old foo.bak is deleted). If you do not like the. results of your edit, the 
UNDC command: 

mv foo.bak foo 
restores the original file foo. 

FILES 

/tmp/MED* temporary workfile (PICK- and CLOSE-buffer) 

SSAVE/MED* saves state of editing session 
/usr/lib/med/default default file 
*.bak backup files 

SEE ALSO 

termcap(5), curses(3), keycap(5) 

AUTHOR 

Dittmar Krall, Wolfratshausen, Germany. 

Inspired by the RAND Editor, Steve Zucker e.a., Santa Monica, California. 

BUGS 

Editor crashes can leave your terminal in a strange state, e.g. with dis¬ 
abled keyboard. Your system administrator should have a command to 
enable the keyboard. My panic solution is to switch terminal off/on in 
order to continue. 
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MED - Tastatur 
fur 


Televideo - 970 


Exit -Z 

save to Disk -D 

-Tab linefeed 

Refresh 

ChTab **T 

ChWin -C 

Left -L 

Right ~R 

Window ~W 

Control char "S 

Macrofunction -F 


Anfang 

Bildschirm 

Home 

CHAR DELETE 

Suche 
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1. Introduction 


The Pascal 68000 User’s Guide is intended for use in developing new Pascal 
programs and in compiling and executing existing Pascal programs on 68000 
UNIX systems. This manual also gives some insight into the Pascal 68000 Sys¬ 
tem structure, its components and its behaviour. 

This manual is designed for programmers who have a working knowledge of 
Pascal. Detailed knowledge of 68000 UNIX is helpful but not essential. In any 
case, it is advisable to get familiar with the UNIX documentation and UNIX 
standards. The user of this manual should also read the QU68000 documents 
[l] and [2]. 

Pascal was designed by Professor N. Wirth as a language for teaching struc¬ 
tured programming techniques and as such is used widely in educational 
institutions. It has also gained popularity as a general-purpose language 
because it contains a set of language features that make it suitable for many 
different programming applications. Pascal has furthermore strongly 
influenced the development of several languages (e.g. ADA). The Pascal 
language includes a variety of control statements, data types, and predefined 
procedures and functions. 

i w~ Throughout this document the following notation is used: 

Keywords and predefined identifiers are printed in bold face. 

Syntactic variables as well as UNIX components are printed in italic font. 

Metasymbols |,{ and [,] are used for optional parts (0..°° and 0..1), (,) 
bracket syntactical units and /'separates alternatives. Three dots (...) 
means a repetition of the preceeding item. Terminal symbols are 
printed in roman face; to distinguish metasymbols from terminal sym¬ 
bols apostrophes ’ are used if necessary. 
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2. Summary Release 2 
2.1. Release 2.1 

• Pascal 68000 release 2.1 meets the suggested Pascal ISO Standard [3] 
more closely than release 1.1 did: 

(1) Type real is implemented. 

(2) Conformant arrays are implemented. 

(3) dispose is available; alternately, mark and release can be used. 

(4) The attribute packed is implemented for subranges. Packing is done 
on byte level but not on bit level. 

• Release 2.1 has some further extensions. 

(1) A type string is predefined and supported by a few operations. 

(2) The attribute packed can be applied to simple types. 

(3) Besides type short there is a type cardinal (unsigned) predefined and 
supported. 

(4) There are new standard procedures pclose and pseek. 

(5) reset and rewrite are extended by a optional second parameter (UNIX 
filename). 

(6) read allows variables of type string. 

• Bits ic Pieces 

(1) A new option v: check arithmetic overflow. 

(2) Naming conventions: the compiler prefixes all imported/exported 
identifiers by an underscore to make the calling of C routines a 
bit more comfortable. 

(3) Some minor, but useful and often used predefined procedures and 
functions. 

(4) Initialisation of the compiler (passl) is partly done by reading a file 
*'init.h", that is supposed to reside in the directory /usr/include/pc. 

(5) Procedures at the outermost level in the main program are exported. 
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2.2. Release 2.2 


• Within modules, variables can be declared at the outermost level. They 
will exist during the whole program, but cannot be accessed from out¬ 
side (static variables). 

■ The size of a procedure is no longer limited. 
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3. Supported Language 


Pascal 68000 is an extended implementation of the Pascal language [4]. 
Specifically Pascal 68000 adheres to the Pascal language as described in the 
suggested ISO Standard. This “draft Standard" is a cleaned up version of the 
original Pascal and has been submitted to ISO for acceptance. 

Pascal 68000 release 2.2 has not yet been tested against a "Pascal Processor 
Validation Suite". 


3.1. Deviations 

Pascal 68000 deviates from the standard proposal in the following ways: 

(1) Only the first 16 characters of an identifier are significant. The trun¬ 
cation of an identifier to 16 characters alters the meaning of a con¬ 
forming program. 

(2) Standard procedures and functions are not allowed as parameters, as 
in previous standard proposals. Identical results with minor loss in 
performance can be obtained by declaring user procedures. For 
example: 

function userodd(i: Integer) : boolean; 
begin 

userodd := odd(i) 
end; 

(3) Procedures that are to be used as parameters must be declared at 
main level. 

(4) files are not allowed in structured data. 

(5) Assignment to for control variable is done after evaluation of initial 
expression. 

(6) The reserved word nil may be redefined. 

(7) A goto between branches of a statement is permitted. 

(8) For textfiles, no final end-of-line is supplied unless requested expli- 
citely by the user. 

(9) If the access to record variable in a with-statement involves only de¬ 
referencing of a pointer variable, this is not done before the state¬ 
ment is executed but for every access to the record. 

(10) A null string is accepted by the compiler. 
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3.2. Extensions 


3.2.1. Separate compilation 

Pascal 68000 is able to compile so called modules, a collection of 
declarations, procedures and functions. The result of the compilation 
(an a.out object module) can be handled by the usual UNIX components, 
i.e. they can be stored in libraries, bound(loaded) with other a.out 
modules, etc. 

The separate compilation feature is further supported by enabling 
import and export of variables, procedures and functions. Modules 
implemented in Pascal, C or assembler can be linked to Pascal 68000 
modules. Procedures and functions are imported by using a directive 
in the heading: extern for Pascal- and assembler- and extemc for C- 
procedures; they are exported implicitely by being defined on the 
outermost level within a compilation unit. The user is responsible for 
parameter and result compatibility. 

Variables are imported or exported by using the newly introduced key¬ 
words import or export instead of var. The predefined variables input 
and output are (per default) exported from a mainprogram, if they are 
listed in the program heading. If used in a module, they have to be 
imported and must be mentioned in read/write statements. It is not 
possible to import or export labels! 

The new syntax for a compilation unit is: 

compilation junit — 

program name ’(’ files ')'; block . 

/module name ; ( declaration J . 

block - 

{ declaration] compound-statement 


3.2.2. Additional standard procedures 

The following additional standard procedures are available: 
addr 

This function returns the address of the parameter, which is com¬ 
patible with ail pointer types. 

convert 

convert (value, typename) returns its first argument as having 
type typename. 

■r* No run-time widening is done; e.g. 

convert (apointer, anotherpointertype) works, but 
convert (‘A’, integer) won’t work! 

mark, release 

mark and release allow to use the heap as a stack, mark(p) stores 
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the current value of the heap pointer in p. release(p) restores the 
heap pointer to p. Within one program either dispose or mark and 
release can be used, but not both simultaneously. 

m- New it dispose are realised by malloc(3) and free(3) which imple¬ 
ment a rather straight-forward memory management. Extensive 
use of heap will therefor result in remarkable run time penalties. 
To avoid this problem, use new with mark & release which use a 
simple and fast memory allocation scheme (seepc(l)). 

pdose, pseek 

They simply supply a Pascal interface to the UNIX system calls close 
and Iseek. 

errorexit — 

Exit a program and force a core dump. 

message 

Write a string to the UNIX file stderr. 
itoa, atoi 

Convert integer to ascii and vice versa, 
date, ptime 

Get date and time in ascii representation, 
clock 

Get cpu time used by the current process. 

3.2.3. Strings 

String variables are unique to Pascal 68000. Essentially, they are of 
type packed array of char with a dynamic ’length’ attribute. The actual 
length of a string is determined by a final zero-byte, string variables 
are not compatible with variables of type packed array [...] of char. No 
range checking is done for string operations. 

The default maximum length of a string variable is 80 characters. This 
value can be overridden in the declaration by appending the desired 
length enclosed by [] : 

var s : string; f 81 bytes will be allocated ) 

var si: string [17]; f 18 bytes will be allocated j 

A string variable has a maximum length of 255 characters. 

Assignment to a string variable can be performed using the assignment 
statement, the read standard procedure or some other routine (e.g. a C 
standard function), strings can be compared, no matter what the 
current lengths are. Furthermore, it is possible to access the com¬ 
ponents of a string variable; the first one has index 0. 

When a string variable is used as parameter to read or readln, all char¬ 
acters up to, but not including, the end-of-line character in the input 
file will be assigned to it. 
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When a siring is written without specifying the field width, the actual 
number of characters written is equal to the dynamic string length. If 
the field width is longer than the dynamic length, leading blanks are 
inserted. If the field width is smaller, the string is truncated on the 
right. 

Constant strings ('hugo') are compatible with type packed array [l..n] 
of char (where n is equal to the string length) and with type string. 
They are also terminated by a zero byte that is not included in the 
length computation and are limited to a length of 255 characters. 

m- Remember that constant *a’ is a character and not a string. 
Strings of length one must be supplied by other means (e.g. a C 
routine). 


3.2.4. Generic pointers 

Generic pointers provide a tool for generalized pointer handling. Vari¬ 
ables of type address can be used in the same manner as any other 
pointer variable with the following exceptions: 

» generic pointers cannot be deferenced since there is no type asso¬ 
ciated with them. 

• generic pointers cannot be used as an argument to new. 

■ any pointer can be assigned to a generic pointer. Use convert for 

assigning a generic pointer to a typed pointer. 

3.2.5. Attribute packed 

As an extension, the attribute packed can be applied also to simple 
types: 

type byte — packed 0 .. 255; 

•| variables of type byte will be allocated one byte { 

Packed subranges that fit in the ranges -2 7 .. 2 7 -l or 0 .. 2 8 -l are 
represented in one byte; those fitting in the ranges -2 15 .. 2 15 -1 or 0 .. 
2 16 -1 are implemented in one word (two bytes). 

This feature is supported by one-byte, two-byte and four-byte signed 
and unsigned arithmetic. But the user should keep in mind, that in 
most cases the packed data have to be extended to a full integer entity. 
See appendix for details. _ 

Types short and cardinal are defined as 
type 

short = packed-32768 .. 32767; 
cardinal = packed 0 .. 65535; 
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3.2.6. Default case 

In a case statement a default case can be defined. Either otherwise or 
else: will be accepted. 

3.2.7. Declaration 

The order of declaration for labels, constants, types, variables, func¬ 
tions and procedures has been relaxed. Any order and any number of 
times declaration sections may be used. Furthermore, import and 
export variable declaration are implemented to support the separate 
compilation feature. 

An identifier must be declared before it is used. Two exceptions exist to 
this rule: 

(1) Pointer types may be forward referenced as long as the declara¬ 
tion occurs within the same type-definition-part 

(2) Functions and procedures may be predeclared with a forward 
declaration. 

The new syntax for a block is: 

block - [declaration] compound-statement 
declaration = 

import (names : type );...; 

/ export (names : type ) ;... ; 

/ var (names : type ) ;... ; 

/ label label, ... ; 

/ const (name —' constant ) ; ... ; 

/ type (name -' type ) ;... 

/function-declaration; 

/ procedure-declaration ; _ 


3.2.8. Underscore as letter 

The character is significant and can be used in forming identifiers. 

3.2.9. Alternate symbols 

There are two representations for comment symbols (’(*’ . '*)’ and ,. 
’{*) and for bracket symbols (*(.’,'.)’ and *[', ’]’). 

3.2.10. Exponent 

A lower case e may be used to indicate real numbers. 

3.2.11. Hexadecimal constants 

Hexadecimal integers are indicated by a preceding The syntax for 
a hexadecimal integer is: 
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unsigned.number - digit ldigitl / # hexadigit \hexadigit\ 

digit sO/1/2/3/4/5/6/7/8/9 

hexadigit * digit /A/B/C/D/E/F/a/b/c/d/e/f 


3.2.12. Character constants 

Certain non-printable characters may be represented according to the 
following table of escape sequences: 

\\ backslash 

\b backspace 

\f formfeed 

\ n newline 

\r carriage return 

\ t horizontal tabulator 

\ddd 

The escape sequence \ddd consists of a backslash followed by 1,2, or 3 
octal digits which are taken to specify the value of the desired charac¬ 
ter. If the character following the backslash is not one of those 
specified, the backslash is ignored. 

3.2.13. Additional predefined identifiers 
See also /usr/include/pc/init.h 


const 

minint — -maxint - 1; 
maxshort = 32767; 
maxcard = 65535 
maxchar = ’\377' 
minshort =-32768; 
mincard = 0; 
minchar = ’\000’; 

type 

alfa — packed array [ 1.. 16] of char, 
short = packed minshort.. maxshort; 
cardinal = packed mincard .. maxcard; 
(address is predefined too} 


var 

argc : integer. 

argv : ~ array [1.. 100] of ** string; 
environ : ~ array [1.. 100] of - string; 


function pclose (var f: flle_of_any_type): integer; externc; 
function pseek (var f: file_of_any_typei offset: integer. 

whence: short): integer; externc; 
procedure message (s: string); externc; 
procedure itoa (i: integer; var s: string); externc; 
function atoi (s: string): integer; externc; 
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procedure date (var datevar: string); extern; 
procedure ptime (var timevar; string); extern; 
function clock : integer; extern; 


3.3. Implementationdefined 

(1) maxint is 2 147 483 647. 

(2) set bounds are 0 and 255. 

(3) A variable is selected before the expression is evaluated in an assign¬ 
ment statement. 

(4) Default field width specification: 

12 for integers, 12 for reals and 5 for booleans. 

(5) reset on the standard input file resp. rewrite on the standard output 
file is permissible. 

3.4. Error Handling 

(1) Uninitialized or undefined variables are not detected. 

(2) A missing reset or rewrite statement is not detected (see 4.3). 

(3) No runtime checks are performed on the tag field of variant records. 

(4) No bounds checking is performed on overlapping set operands. 

(5) The use of a function without an assignment to the function value 
variable is permitted. 

(6) No checks are inserted to check pointers after they have been 
assigned a value using the variant form of new. 

(7) No bound checks are inserted for the succ, pred or chr functions. 

(8) The evaluation of expressions involving big constants can cause com¬ 
piler crash. 

(9) The for control variable is not invalid after the execution of the for 
statement. 

(10) Two nested for statements with the same control variable are permit¬ 
ted. but do not run into an infinite loop. 
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(11) Type declarations of the kind 


type t = typer, 


procedure p; 
type 

pt = ~ t; 
t = type 2-, 

are not correctly analysed. 


Pascal 68000/2.3 




4. Pascal 68000 under UNIX 


4.1. Creating and executing a program 

The usual way to create and execute a program is realized by entering the 
following commands to the 68000 UNIX operating system. With each com¬ 
mand. you include information that further defines what you want the sys¬ 
tem to do. Of prime importance is the file specification, which indicates 
the file to be processed. You can also specify qualifiers that modify the 
processing performed by the system (* is the system prompting symbol). 

A program is entered or corrected by any editor of the user's taste. The 
file name of Pascal source programs must have the suffix ’.p'. 

S edit <name>.p cr 

The pc [5] command compiles and links the Pascal program. The resulting 
object module is left in <name>. 

S pc -o <name> <name>.p cr 

The program is loaded and run by: 

S name cr 

The only program parameters supported by the Pascal language are files. 
There are three ways to associate an (external) UNIX file specification with 
an (internal) Pascal file specification. The standard Pascal files input and 
output are always associated with the logical UNIX files sfdtn and stdout. 
Their comfortable and flexible use is described in [6]. All other Pascal 
files can be associated with any UNIX file either by assignment within a 
commandline: 

S name pascalfile_l=UNIX_file_specification \ 
pascalfile_2=UNDC-file-specification 1 \ 

. .. CR 

or - if an assignment is missing - interactively: 

S name pascalfile_2=UNDC_file_specification cr 
pascalfile-l ? UNDC_file_specification cr 


1 As these assignments are considered as one argument each, there must be no blanks before 
or after the sign. 
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Example: 

S ed example.p cr 
S pc -o example example.p cr 
S example eingabe=/dev/tty cr 

ausgabe ? example.aus cr , 

It is advisable to define a shell procedure for a more convenient file 
assignment especially if some of the files are "fixed” or work files. 

As an extension of Pascal 68000, the external filename can be stated in 
the corresponding reset or rewrite statement. In this case, a file assign¬ 
ment at run time will be meaningless. 

For efficiency, output is in general buffered: the buffer is flushed only 
when it's full, or - in case of text files - if a writeln is stated. To facilitate 
interactive I/O, output to a file of char will be unbuffered, if the file is con¬ 
nected to a terminal {/dev/tty). Input from a terminal is line-oriented 
unless the terminal is in raw mode (see stty(l), ioctl(2)). 


4.2. Support of UNIX Facilities 

The user has full access to all UNIX system calls as well as files. The system 
calls can be accessed just like C procedures (see below). The objects are to 
be found in the standard library. The predefined procedure halt provides 
a means to return an "exit code" to the system. Furthermore the "system 
variables" argc, argv and environ are provided for access to the command 
arguments and the process environment, argc indicates the number of 
arguments whereas argv references an array of argument strings. The 
actual length "i" of environ is determined by environ~[i] = nil. See 3.2.13 
for a declaration of these variables. 

Remember that the file specifications are command arguments too, i.e. 
argv~[l]~[0] is the first character of the program name. If you access 
argv~ or environ^, it is essential to switch off the pointertest. 

Example: 

The following statement will print out the environment: 

{St-{ 

begin 

i := 1: 

while environ^ (i) <> nil do 
begin 

writeln(output, environ~[i]~); 
i := i+1 
end 
end; 

The C preprocessor cpp [7] may be used without limitations. 
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As stated earlier C and assembler modules can be loaded with Pascal. 
When connecting Pascal modules with C modules you should take care of 
parameter compatibility (see 9.). Moreover, you must be sure that the C 
modules do not use the sbrk/brk system call which interferes with the 
Pascal heap. 


4.3. Limitations of Pascal 68000 

• Because of the separate compilation feature, a missing reset or 
rewrite cannot be detected by the compiler and will most probably 
cause the program to crash with an address error at the first attempt 
to access the corresponding file-variable. 

■ In general, it is possible to reset input or rewrite output with the 
effect, that stdin or sfctouf is repositioned to the beginning of the 
associated file. If the file is connected to a pipe this will have no 
effect at all. 

• Because of a very straight-forward register allocation mechanism, 
there may be very deeply nested expressions that do not compile. 
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5. Compiler options 

0 ■ 

Compiler options are given by using "(S...}". Each option consists of a lower 
or upper case letter followed by “+” or *'- M . Options are separated by com¬ 
mas. There must be no blanks between "j" and "8” or between a comma and 
the succeeding option. The following options are supported: 


A/a +/- 
B/b +/- 
D/d +/- 

E/e +/- 
P/p +/- 
T/t +/- 
V/v +/- 
W/w +/- 


a+ produces an assembler listing 
b+ accept C-string notation (i.e. with backslash) 
d+ produces code for pointer, subrange and arithmetic overflow 
check and the tracing of line numbers 
e- will suppress extension warnings 
p+ code for profiling is generated (see prof [8]) 
t+ produces code for pointer check 
v+ produces code for arithmetic overflow check 
w- will suppress warning messages 


Defaults: |8a-,b+,d+.e-,w+J 

d+ implies v+ and t+. 
d - implies v - and t 


Options appearing before the program or module symbol can be overwritten 
by options given in the pc command. 
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6. Error handling 

Errors are detected and reported by several components of the Pascal 68000 
system: 

- preprocessor cpp, see pc 

- compiler 

- loader Id, see pc 

- run-time system 


6.1. Compile time Detection of Source Errors 

passl detects syntactical and some semantical errors and (optionally) 
deviations from the standard language definition. Errors that are not 
detected are listed in 3.4. passl does not produce error messages or a 
listing but compiles a condensed version of the diagnostics that will be 
printed in a readable form by an extra pass perror. If only warnings are 
issued compilation proceeds otherwise it will be terminated. 

The option "-L" (see pc) produces a full listing with error messages. The 
default is a listing containing the offending line, its predecessor and the 
readable (and hopefully understandable) error messages. Sometimes an 
error causes several messages to be printed in which case all but the first 
one cam be ignored. 

pass2 detects no source errors, but might report a violation of a compiler 
limitation (see 4.3) or a compiler error (though, of course, it should not). 
Please let us know if you get an compiler error or an unknown error mes¬ 
sage. 


6.2. Other Errors Detected at Compiletime 

During compilation, UNIX resources can be exhausted, e.g. file system, pro¬ 
cess table, or memory overflow, etc. Furthermore UNIX can deny access to 
files. Extensive treatment of these errors is beyond the scope of this 
manual. They are described in the UNIX documentation. 


6.3. Runtime errors 

Errors occurring at run time are always fatal, i.e. the program will report 
an error message, dump the core file and then abort. With the help of the 
UNIX debugger adb [9] the user can generate a (partially) symbolic post 
mortem dump which indicates the location of the fatal error, the number 
of the corresponding source line (if the debug option was on), the dynamic 
calling sequence, etc. 

The error message should comprise a sufficient diagnosis of the error 
detected. As far as file access is concerned, the errors are mostly 
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reported by the UNIX system and must be investigated using the documen¬ 
tation. Other messages indicate programming errors such as divide by 
zero, integer overflow , etc. 
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7. Pascal System Components 


Figure 7.1 gives an overview of the Pascal system components. The prepro¬ 
cessor is the same as the C-compiler’s, and does macro preprocessing and 
including of source files. 

The first pass passl does the lexical, the syntactical and the semantical 
analysis. It constructs a parse tree for each block and outputs it. 

There is an extra pass perror to produce a source listing if requsted, and to 
print error messages based on the diagnostics compiled by passl. 

The second pass pass2 does the code generation. The output of passl is read 
in and an identical parse tree as in pass! is built up. The generated code is 
output in several files. 


init.h <source>.p 



i 

<source>.o 


<1 


4 

a.out 


Figure 7.1: Pascal System Components 
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The third pass c2 is the same as the C-Corcpiler’s and collects the code distri¬ 
buted on various files. It produces one file containing the object code in a.ouf 
format [10]. 


7.1. Hardware and Software Environment 

Pascal 68000 runs on two quite similar 68000 UNIX systems. PERKEO [ll] 
and QU68000 [12]. 

Features of these systems are: 

• actually supported microprocessor Motorola 68000 

• large memory ( & 0.5 MB ) 

• hard disk ( 10MB ) 

• memory management unit 

UNIX [13] [14] is a time-sharing system and provides all such features 
needed by Pascal 68000. Of great importance are the file system, the 
command interpreter (shell), and the object module management (or. Id 
[15]). But of equal, if not greater, weight are all those UNIX components 
which make life easier: ed, med, make, etc. 


7.2. Passl 

The first pass does lexical analysis, parsing, declaration handling, tree 
building, and some optimization. This pass is largely machine independent. 

The lexical analysis is a conceptually simple procedure that reads the 
input and returns the tokens of the Pascal language as it encounters 
them: identifiers, constants, operators and keywords. Comments must be 
skipped. Decimal and hexadecimal constants, characters and strings must 
be properly dealed with. 

The first pass parses, as the original Pascal-P4 compiler, the tokens in a 
top down, left right, recursive descendent fashion. During the processing 
of a declaration part a symbol table is built up, addresses will be allocated 
to variables and procedures, and the semantic of the declaration is 
checked. Besides this, information is prepared for the debugger adb. 

During the processing of the statement part a parse tree is built. The 
proper use of operators and operands is checked. Some complex syntacti¬ 
cal structures are broken down into simpler ones. 


Pascal 68000/2.3 


19 





7.3. Pass2 


The second pass generates 68000 machine code and related information 
from the source program represented by the parse tree; these will be 
combined to a a.out object. In addition it completes the debugger informa¬ 
tion prepared by pass i. 

Code generation is done in two steps. The first one traverses the parse 
tree generating pseudo instructions for a hypothetical stack machine. 
This step is rather simple, machine independent and straightforward. The 
second step deals with machine specific tasks such as address computa¬ 
tion, register allocation and 68000 code generation, thus interpreting the 
pseudo instructions in a real existing environment. Step one and two take 
place in parallel for efficiency reasons; the generation of a pseudo 
instruction is replaced by calling a procedure implementing this instruc¬ 
tion. 

pass2 yields different kinds of output. Three files contain binary informa¬ 
tion ready to be combined to an a.ouf object by a third pass. A fourth file 
may contain the generated machine code in an assembler-like representa¬ 
tion. On another file debugger information is prepared. And there' might 
be diagnostic messages indicating a violation of a limitation or a compiler 
error. 


7.4. Cross Reference 

The cross reference program xref produces the usual cross-reference list 

with identifiers and line numbers. 

xref is implemented as an independent component. There are several rea¬ 
sons for doing so: 

• The compiler is not bothered with cross referencing. 

• The multiprogramming (parallel processing) of the system can be 
exploited. 

• Many programming errors can be found with the help of a cross- 
reference listing; i.e. it is not necessary to start the big, resource 
consuming, compiler. 
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8. Calling Conventions 


Procedure calls are realised by a commonly used mechanism defining stack- 
frames, which are allocated or deallocated as a procedure is activated or 
deactivated, respectively. In our implementation four registers and a vector 
of pseudo registers are used: a7 is used as stackpointer, &6 and a5 reference 
the current and the global stackframe base, respectively. dO returns a func¬ 
tion result and the system variable _pbvec[0..maxdepth] stores the base 
addresses of all currently accessible stackframes. The layout of a stack- 
frame is shown below. 


stackframe 



(i = current nesting depth) 


A parameter is passed by-reference or by-value depending on whether it was 
declared as var parameter or not. For long parameters (> 4 bytes; strings) 
the parameter address is transferred and - in case of value parameters - the 
parameter itself copied within the procedure body. The representation of 
parameters in memory is the same as for other variables with the exception 
that they are always word aligned, i.e. a parameter occupying an odd number 
of bytes in memory will always be followed by a byte of undefined storage. 


Example: 
stackframe for 

procedure p(var j:integer c,d:char; s:string); 
after procedure entry 


12 


ie 17 is to 20 


,pbvec 


old aO 


retaddr 


addr(j) 


addr(s) 


t 

aO 


• undefined 


The C interface provided as an extension differs from the Pascal parameter 
passing conventions only in the treatment of one-byte values; following the C 
semantics, data occupying one byte of storage are extended to (unsigned) 
word values and then treated like a short 
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Example: 
stackframe for 

procedure p(var j:integer c.d:char; i:integer); externc; 
after procedure entry 


>2 14 ia 


old &6 


re tad dr 


addr(j) 


t 

&6 



where c & d are pushed as zero extended short items 
(at our installation Pascal short corresponds with C int). 
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9. Data Representation and Allocation 

In a.out modules program data fall into three segments: the text segment, 
the data segment and the bss segment. Pascal 68000 uses only two of them: 
the text segment contains program code and constants whereas static data 
(variables declared at the outmost level in a module) and exported variables 
are stored in the bss segment. Automatic and dynamic data are allocated at 
runtime in stack and ‘free memory' managed by the brk/sbrk system calls, 
respectively. 

To cope with alignment, one general rule can be stated: any data allocated 
more than one byte is aligned on a word (2 bytes) boundary. 

Variables of scalar and pointer types are allocated storage space as summar¬ 
ized in table 9.1. Variables of subrange types are allocated as variables of the 
associated scalar types. For example, a type 1..10 is considered a subrange of 
integer and therefor allocated a longword. Variables of packed subrange 
types are implemented in one byte (-128 .. 127; 0 .. 255), two bytes (-32768 .. 
32767; 0 .. 65535) or four bytes (all others). The structured types are stored 
as described below. 


Type 

Storage 

Allocation 

character 

8 bits (1 byte) 

Byte 


boolean 

8 bits (1 byte) 

Byte 


short 

16 bits (1 word) 

Word 


integer 

32 bits (1 longword) 

Word 


real 

32 bits (1 longword) 

Word 


enumerated 

8 bits (1 byte) if 
type contains 256 
elements or less; 
16 bits (1 word) 
otherwise 

Byte if 

contains 
elements or 
Word otherwise 

type 

256 

less; 

pointer 

32 bits (1 longword) 

Word 



Table 9.1: Storage of Scalar and Pointer Types 


A set is allocated storage depending on the ordinal value of its largest ele¬ 
ment: the number of bytes it occupies is equal to the ordinal value rounded 
up to the nearest byte boundary. Since the size of a set is limited to 256 
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elements, with ordinal values from 0 to 255, a set occupies at most 32 bytes. 

An array is stored and aligned according to the type of its components. For 
example, each element of a character array is stored in a byte and aligned 
on a byte boundary; if the array has more than one component then the 
total array is aligned a on word boundary. Similarly, each element of an 
array of set of 3..21 occupies three bytes and is aligned on a word boundary. 

strings and constant strings are internally terminated by a binary 0; i.e. they 
adhere to the C convention. 

Records are stored and aligned field by field according to the type of the 
field. For example, a variable of type 

record 
x: integer, 
y: boolean; 
z: 1..10 
end; 

is aligned on a word boundary because it occupies more than one byte of 
storage. The figure beneath shows how this variable is stored: 

I x I y I * I z 

• undefined 

The attribute packed does not affect the allocation of data structures; it is 
only interpreted with subranges as stated earlier. To yield a more compact 
representation than in the example above, you had to define the following 
structure: 

record 
x: integer; 
y: boolean; 
z: packed 1..10 
end; 

which would result in the following storage allocation: 
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10. Appendix 


10.1. Examples 

10.1.1. Sample program 

1 program ackermann(input.output); 

2 var x, y: integer; 

3 function ack(i,j: integer): integer; 

4 begin 

5 if i = 0 then ack:=j+l 

6 else if j = 0 then ack:=ack(i-l,l) 

7 else ack:=ack(i-l,ack(i,j-l)) 

8 end; 

9 

10 begin 

11 repeat 

12 writeln(output,'Enter two integers. Terminate with zero.'); 

13 read(input,x,y); 

14 writelnCoutput.'ackerO.xrO.WyiO.’) = \ack(x,y):0) 

15 until x=0 

16 end. 


10.1.2. Crossreference 


ack 

3p 

5 

6 

6 

7 

ackermann 

1 





i 

3f 

5 

6 

7 

7 

input 

1 

13 




integer 

2 

3 

3 



j 

3f 

5 

6 

7 


output 

1 

12 

14 



read 

13 





X 

2v 

13 

14 

14 

15 

y 

2v 

13 

14 

14 
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10.1.3. Separate Compilation 


1 program ackermann(input.output); 

2 var x, y: integer; 

3 

4 import counter: integer; 

5 

6 function ack(i,j: integer): integer; extern; 

7 

8 begin 

9 repeat 

10 writeln(output,’Enter two integers. Terminate with zero.'); 

11 read(input,x,y); 

12 counter:=0; 

13 writeln(output,’acker(’,x:0,y,y:0,') = \ack(x.y):0); 

14 writeln(output,*number of calls=\counter:5); 

15 until x=0 

16 end. 

1 module ack; 

2 

3 export counter: integer; 

4 

5 function ack(i,j: integer): integer; _ 

6 begin 

7 counter:=counter+l; 

8 if i = 0 then ack:=j+l 

9 else if j = 0 then ack:=ack(i-l,l) 

10 else ack:=ack(i-l,ack(i,j-l)) 

11 end; 

12 . 
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10.2. Coercions 


The following gives an overview about the coercions implemented by Pas¬ 
cal 68000 to provide for consistent use of one-, two- and four-byte signed 
and unsigned operands. The rules are valid for all arithmetic and rela¬ 
tional operations. 

Index expressions are always extended to a full integer value. Expressions 
representing setelements are considered unsigned one-byte. 



f 

i 

il 

i2 

u 

ul 

u2 

f 

f 

f 

f 

f 

f 

f 

f 

i 

f 

i 

i 

i 

i 

i 

i 

il 

f 

i 

il 

i 

i 

i 

i 

i2 

f 

i 

i 

i2 

i 

i 

i 

u 

f 

i 

i 

i 

u 

u 

u 

ul 

f 

i 

i 

i 

u 

ul 

u 

u2 

f 

i 

i 

i 

u 

u 

u2 


Notation 

f: floating point 

i: (signed) integer 
u: unsigned (0 .. 2 31 -1) 

il: one-byte integer 

il: two-byte integer 

ul: one-byte unsigned 

u2: two-byte unsigned 
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10.3. Standard Procedures and Functions 

For a detailed description see [3], [4]. 


Procedure 

Parameter 

Result 

Function 

abs(x) 

integer or real 

same as x 

Computes the absolute value 

of X. 

addr(x) 

any type 

address 

Type address is compatible 
with all pointer types. 

arctan(x) 

integer or real 

real 

Computes the arcus tangens 

of X. 

atoi(s) 

string 

integer 

Convert ascii string to 
integer. 

chr(x) 

integer 

char 

Returns the character whose 
ordinal number is x. 

clock 


integer 

Returns the cpu time (in 
milliseconds) used by the 
current process. 

convert(a.t) 

any type 

t 

Returns value of a with type 
t. 

cos(x) 

integer or real 

real 

Computes the cosinus of x. 

date(x) 

string 


Return date in ascii 

representation: 

dd-mon-yyyy 

eof(f) 

file 

boolean 

End of file encountered, true 
only when the file position is 
after the last element in the 
file. 

eoln(f) 

file 

boolean 

End of line encountered, 
true only when the file 
position is after the last 
character in a line. The value 
of f~ is a space. 

errorexit 



Exit program and force a 


core dump. 
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exp(x) 

integer or real 

get(f) 

file 

halt(x) 

integer 


halt 


itoa(i.s) 

integer.string 

ln(x) 

integer or real 

mark(x) 

any pointer 

message(x) 

string 

new(p) 

any pointer 

new(p,tl,..tn) 


odd(x) 

integer 

ord(x) 

any scalar type 
except read. 

pack(a.i.z) 


page(f) 

file 

pclose(f) 

file 
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real Computes the base of the 

natural logarithmus raised to 
the power of x. 

Moves the current file 

position to the next element. 

Terminates the execution of 
the program and returns the 
value of x. See also the 
system call exit(2). 

same as halt(O). 

Convert integer to ascii; the 
result is delivered in variable 
s. 

real Computes the natural 

logarithmus of x. 

Stores the current value of 
the heap pointer into x. 

Write string to stderr. 

Allocates heap memory and 
returns the address in p. 

Allocates heap memory to 
pointer. p~ must be a record 
with variants. 

boolean Returns true if the integer x 
is odd; false otherwise. 

Returns the ordinal (integer) 
value corresponding to the 
value of x. 

z:=a[i..n]; 

where i..n: index range of z. 

skip to the top of a new page 
before printing the next line 
of the textfile f. The default 
for f is output. 

See system call close (2). 
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pred(x) 

any scalar type 
except real 

same as x Returns the predecessor 
value of x. 

pseek(f,o,w) 

file, integer, 

short 

See system call lseek (2). 

ptime(x) 

string 

Return time in ascii 

representation: 
hh-mm-ss.O . 

put(f) 

file 

Appends f~ to the file f. The 
default for f is output. 

read(f.x) 

file 

type of x 
depends on the 
filetype 

Reads the value of x from the 
file f. The default for f is 
input. 

readln(f) 

text 

Skips to the beginning of the 
next line. The default for f is 
input. 

read(f.xl,..,xn) 


same as 

read(f.xl); read(f,x2,..xn) 

readln(f ,xl ,..,xn) 

same as 

read(f,xl,..,xn); readln(f) 

release(x) 

any pointer 

Loads the heap pointer with 
the value of x. 

reset(f[,s]) 

file,string 

Resets file for reading. The 
optional second parameter 
designates a UNIX pathname. 

rewrite(f[.s]) 

file,string 

Resets file for writing. The 


optional second parameter 
designates a UNIX pathname. 


round(x) 

real 

integer 

trunc(x + 0.5) if x >= 0 
trunc(x - 0.5) if x < 0 

sin(x) 

integer or real 

real 

Compute sinus of x. 

sizeof(x) 

any type 

integer 

Returns size used to 

represent variables of same 
type as x. 

sqr(x) 

integer or real 

same as x 

Computes the square of x. 
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aqrt(x) integer or real 

real Compute square root of x. 

succ(x) any scalar type 

except real 

same as x Returns the successor value 
of x. 

trunc(x) real 

integer Truncate x to a integer value. 

unpack(z.a.i) 

a[i..n]:=z; 

where i..n: index range of z. 

write(f.x) text 

type of x 
depends on the 
filetype 

Writes the value of x to the 
file f. The default for f is 
output. 

writeln(f) file 

Starts a new line. The 
default for f is output. 

write(f,xl,..,xn) 

same as 

write(f,xl); write(f,x2,..xn) 

writeln(f,xl,..,xn) 

same as 

write(f,xl,..,xn); writeln(f) 


Pascal 68000/2.3 


31 





10.4. Syntax Equations 


letter - a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z 
/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O/P/Q/R/S/T 
/U/V/W/X/Y/Z/- 

digit = 0/1/2/3/4/5/6/7/8/9 

name = tetter ( tetter / digit j 

constant jiame = name 
type .name = name 

variable .name = name . 

names — name ,... 

label = unsigned-number 

compilation-unit — 
program '(* names ; block . 

/ module name ; (declaration) . 

blocifc = (declaration) compottnd_sfatement 

declaration = 

/ import f names : type );...; 

/ export ( names .* type ) ;... ; 

/ var (names : type ) ;... ; 

/ label label ,... ; 

/ const (name '=' constant );... ; 

/ type (name ‘=‘ type ) ;... ; 

/function-declaration ; 

/procedure-declaration ; 

constant = 

[ sigm ] f unsigned-number / constant-name ) 

/ character string 

sign = + /- 

unsigned-constant = 

unsigned-number / character string 
/ constant-name / nil 

unsigned-number — 

digit (digit) / # hexadigit ( hexadigit] 

hexadigit - digit /A/B/C/D/E/F/a/b/c/d/e/f 

character string = /^characters enclose by ' ' */ 
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type - type .name / newjtype 

new-type = simple-type / structured-type /- type .name 

simple -type = ordinal-type / real 

ordinal-type = 

Y names '/ 

/ constant .. constant 
/ ordinal-type-name 

structured-type = 

[ packed ] unpackedstructured-type 
/ structured-type -name 

unpackedstructured-type = 

array *[’ ordinal-type ,... *]• of type 
/ file of type 

/ record [ field-list [; ] ] end 
/ set of ordinal-type 

field-list = 

fixed-part [ ; variant-part ] 

/ variant-part 

fixed-part = f names : type ) ;... 

variant-part = case [ tag-field-name : ] tag-type of variant ;... 

variant - casesonstant-list:'( [ field-list [;]]*/ 

case -constant-list = casesonstant ,... 

case sonstant = constant [ .. constant ] 


- expression - 

variable = (variable-name / field-name ) 

( ’[' expression ,... *]* 

/. field-name 

factor — 
variable 

/ unsigned sonstant 

/ function-name [ Y actual-parameter , ... */ ] 
/set 

/ 'C expression ’/ 

/ not factor 

actual-parameter — 
expression 

/ procedure .name / function-name 
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set = *[• [ member ,... ] *]* 

member = expression [ .. expression ] 

term = factor 

j ( * / ’/■ / dir / mod / and ) factor j 

simple expression = [ sign ] term 
{ ( + / - / or ) term j 

expression = simple expression 
[(<>/=/</>/<=/<=) simple expression ] 


procedure - 


procedure -declaration = 
procedure sheading ; 

( block / directive ) 


function^declaration = 
functionJieading ; 

( block / directive ) 

directive — forward / extern / externc 

procedure-heading — procedure name [ ' C parameter ;...'/] 

function-heading = function name [*f parameter ;... ’)'] 

: result-type 


parameter — 

function-heading / procedure-heading 
/ names : type 

/ var names : (type-name / array-type ) 
array-type = 

array *[• index .type ; ... *]* of (type-name / array-type ) 
index-type - 

name .. name : ordinal-type-name 




- statement - 

statement = [ label: ] 
compound-statement 

/ case expression of case-element ;... [; ] end 
/ for name expression 

(to / downto ) expression 
do statement 
/ goto label 

/ if expression then statement 
[ else statement ] 
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/ repeat statement ; ... until expression 
/ while expression do statement 
/ with variable ,... do statement 
/ ( variable / function_name ) := expression 
/ procedure-name [ 'C actual ^parameter ,... •)' ] 

compound-statement = 
begin statement ;... end 

case element = 

( ( case .constant / else ): / otherwise ) 
statement 
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10.5. Reserved Identifiers 


The following identifiers are predefined by Pascal 68000. 


abs 

environ 

mincard 

readln 

addr 

eof 

minchar 

real 

address 

eoln 

minint 

release 

alfa 

errorexit 

minshort 

rewrite 

arctan 

exp 

new 

round 

argc 

false 

nil 

short 

argv 

get 

odd 

sin 

atoi 

halt 

ord 

sqr 

boolean 

integer 

pack 

sqrt 

cardinal 

itoa 

page 

succ 

char 

In 

pclose 

text 

chr 

mark 

pred 

true 

clock 

maxcard 

pseek 

trunc 

convert 

maxchar 

ptime 

unpack 

cos 

maxint 

put 

write 

date 

maxshort 

message 

read 

writeln 


Furthermore, there are identifiers of data and subroutines used by the 
Pascal run time system that are referenced at linking time. Among them 
are system calls (e.g. open, close) and some C standard subroutines; all 
others are listed below. Warning: the user might use this identifiers to 
define own procedures or data and the linker Id will reference the users’ 
entity and report no error. 


_copen 

_pconf 

.pperr 

-pwrf 

_divl0 

.pemptyset 

_prdi 

-pwri 

_entry 

.pemptystr 

_prdr 

-pwrr 

.error 

.phigh 

_prds 

_pwrs 

.Terror 

.pierr 

_pserr 

-jsyserr 

.flushbufler 

-Pjerr 

.pstaticstring 

a tan 

.pblank 

.plim 

.puerr 

closefiles 

_pbvec 

.plow 

_pwrb 

final 

.pease 

.popen 

_pwrc 

fsqr 

_pcerr 

.popenfileindx 

.pwrcl 

In 

.pclose 

.popenfiles 


main 
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Berkeley Extension Summary 



Trademarks: 


MUNIX, CADMUS 

for PCS 

DEC. PDP 

for DEC 

UNDC 

for Bell Laboratories 


Copyright 1984 by 

PCS GmbH. Pfalzer-Wald-Strasse 30, D-8000 MQnchen 90, tel. (089) 67804-0 

The information contained herein is the property of PCS and shall neither be 
whole or in part without PCS’s prior written approval nor be implied to grant 
make, use or sell equipment manufactured herewith. 

PCS reserves the right to make changes without notice in the specifications 
contained herein and shall not be responsible for any damages (including 
caused by reliance on the materials presented. 


reproduced in 
any license to 


and materials 
consequential) 





The MUNIX extension package consists of utilities of the fourth Berke¬ 
ley Distribution. This manual contains the command descriptions and 
supplementary documents. 


1. MUNIX Extension Package - Summary 
Features of the extension package. 

2. Writing Papers with nroff using -me 
A popular macro package for nroff. 

3. -me Reference Manual 
The final word on -me. 

4. Writing tools - the Style and Diction Programs 

Description of programs which help you understand and improve 
your writing style. 

5. The Berkeley Font Catalog 

Samples of fonts currently available for the raster plotters. 

6. Screen Updating and Cursor Movement Optimization 

Description of a package of C library functions which allow screen 
updating (with user input) and cursor motion optimization. 

7. Command Descriptions in MUNIX la ("Berkeley") 

Command descriptions in the style of the MUNIX Programmers’ 
Manual Volume I. 













HUNIX Extension Package Vl.l * Summary 
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The HUNK Extension Package includes a set of useful utilities from the 
fourth Berkeley Distribution. Some of them are extensions of UNDCt V7 com¬ 
mands, i.e. cat and man, others are complete new. The most important facil¬ 
ity of this package is the screen oriented editor VI. 


1. Basic Software 

1.1. User Access Control 

CHFN Change full name of user. The geos field of the passwd-file is used 
to give additional information about the user like phone number, 
office... 

1.2. Terminal Handling 

TSET Set terminal modes. 

RESET Reset the terminal bits to a sensible state. Useful after a program 
dies leaving a terminal in a funny state. 

CLEAR Clear terminal screen. 

LOCK Reserve a terminal. 

1.3. File Hanipulation 

CAT Concatenate and print one or more files onto standard output. 

Additional options to the CAT command of the 7th edition: 

# Numbering of output lines. 

# Crushing out multiple adjacent empty lines. 

# Printing non-printing characters in a visible way. 

SEE Print a file which contains non-printing characters in a readable 

format. 

HORE Interactive display function for text files. 

§ Start at linenumber i or two lines before pattern. 


|UNIX is a Trademark of Bell Laboratories. 
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# Display next page or i-more lines. 

# Skip i lines. 

# Search i-th occurence of pattern. 

# Display current filename, current line number. 

# Define window size. 

# Squeeze multiple blank lines. 

# Start up the editor VI at current line. 

# Exit to Shell. 

# Help function. 

VPR Raster printer/plotter spooler. 

HEAD Give first few lines of a stream. 

STRINGS Look for ASCII strings in a binary file; 

FOLD Fold long lines for finite width output device. 

NUM Number lines. 

UL Do underlining. 

COLRM Remove selected columns from a file. 

EXPAND 

UNEXPAND Expand tabs to spaces and vice versa. 

COMPACT 

UNCOMPACTCompress and uncompress files using an adaptive Huffman code. 
CCAT Cat the original file from a file compressed by compact, without 
uncompressing the file. 

1.4. Running of Programs 

YES Be repetitively affirmative. Outputs *y’. 

1.5. Status Inquiries 

FINGER List the current users including login name, terminal name, login 
time... 

W Print a summary of the current activity on the system, including 

what each user is doing. 

USERS Print a compact list of users who are on the system. 

UPTIME Show how long system has been up. 


1.6. Backup and Maintenance 

SHUTDOWN Close down the system at a given time. Used to notify users nicely 
when the system is shutting down. 

BAD SECT Create files to contain bad sectors. Less general than bad block 
forwarding, but better than nothing. 

SCRIPT Make a typescript of everything printed on the terminal during a 
session. 
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DMESG Look in a system buffer for recently printed diagnostic messages 
and print them on the standard output. 

1.7. Acco u nti ng 

SA Publish Shell accounting report. Gives usage information on each 

command executed. Additional options to the SA command of the 
7th edition. 

§ Number of tiroes used. 

f Total system time, user time and elapsed time, 
f Optional averages and percentages. 

# Sorting by different criterions: 
disk 1/0 operation 
cpu-time average memory usage 
cpu-storage integral 
number of calls 

LAST Indicate last logins of users, groups or on specified terminals. 
LASTCOMM Show last commands executed in reverse order. 

1.8. Communication 

HSGS Read system messages. These messages are sent by m ai l i n g to the 
login ‘msgs\ 

BIFF Be notified if mail arrives and who it is from. 

FROM Show who is the sender of my m a i l. 

PRMAIL Print the mail which waits for you. or a specified user, in the ‘post 
office'. 

LEAVE Remind you when you have to leave. 

1.9. Basic Program Development Tools 

CURSES Library of screen functions which allows screen updating (with 
user input) and cursor motion optimization. 

WHAT Show what versions of object modules were used to construct a 
file. 

ERROR Analyze and disperse compiler error messages. 

# Knows about error messages produced by MAKE, CC, CPP, AS, 
LD. LINT. PC, F77. 

# Attempts to determine which language processor produced 
each error message. 

§ Determines source file and line number to which the error mes¬ 
sage refers. 

| Determines if the error message is to be ignored, or not. 

§ Inserts the error message into the source file as comment 
PRINTENV Print out the values of the variables in the Shell environment. 
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1.10. Unix Programmers' lianual 


MAN 


CATMAN 

APROPOS 

WHATIS 


Give information from the on line programmers’ manual. 

# Gives all commands whose description contains any of a 
specified set of keywords. 

# Attempts to locate manual sections related to a specified list of 
files. 

# Formats a specified set of manual pages. 

Create the preformatted versions of the on-line manuals. 

Show which manual sections contain instances of any of the given 
keywords in their title. 

Look up a given command and give the header line from the 
manual section. 


WHERE1S Locate source, binary, and or manual for specified files. 


2. Tape Manipulation 

MT Give commands to the tape drive. 

# Space forward i files or records. 

# Space backward i files or records. 

# Write i end-of-file marks. 

# Rewind tape. 

§ Swap or do not swap bytes. 

REWIND Rewind the tape drive. 

3. Text Processing 

3.1. Document Preparation 

EX The line oriented text editor EX is a superset of the ED editor 

from UNIX V7 and the root of the interactive display function VIEW 
and the family of editors: EX. EDIT, VL 

# Find lines by number or pattern. 

# Add, delete, change, copy, move or join lines. 

# Permute or split contents of a line. 

# Replace one or all instances of a pattern within a line. 

§ Combine or split files. 

# Switch to the location of a 'tag'. 

§ Enter intraline editing. 

# Reverse the effects of the last command. 

# Escape to Shell during editing. 

# Indent automatically. 

# Define abbreviations. 

# Attempt to recover the buffer in case of hangups or crashes. 

' § Read and execute commands from a specified file. 
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EDIT 


VI 


VIEW 

CTAGS 

MKSTR 


XSTR 


§ Simulate an intelligent terminal on a dumb terminal. 

A small version of EX. Avoids some of the complexities of EX to pro¬ 
vide an environment for new and casual users. 

§ Find lines by number or pattern. 

# Adi delete, change, copy or move lines. 

§ Replace a pattern in a line. 

# Add the contents of a file. 

§ Reverse the effects of the last command. 

§ Escape to Shell. 

f Attempt to recover the buffer in case of hangups or crashes. 

The screen oriented editor VI is based on EX (see above). Addi¬ 
tional attributes: 

§ Numerous commands for file manipulation, 
i.e. edit file containing the tag ‘tag’ 
at the first line of ’tag’ 

| Extensive command set for scrolling, paging and cursor motion, 
i.e. move to the end of line 

move to the begin of the next word 

jjt Various uni* g of text can be handled: words, sentences, sec¬ 
tions. 

i.e. duplicate sentence 
delete word 

f Searching for strings by a set of different conditions, 
i.e. matches any character between ‘x’ and *y* 
matches the end of a word 

# Definition of macros for saving time by typing commands. 

# Escape to the line oriented editor EX. 

Interactive display function. Works like the VI - but with read-only 

files. _ 

Make a tags file for EX from the specified C, PASCAL and FORTRAN 
sources. A tags file gives the locations of specified objects (in this 
case functions) in a group of files. 

Used to create a file of error messages by massaging C source 
code. 

# Places all error messages from a C source file in a specified file. 

# Keys on the string •error("* to process the error messages to 
the message file. 

# The copy of the C source file contains pointer into the message 
file to retrieve the error message. 

Extract strings from C programs to implement shared constant 
strings. 

# Maintains a file into which strings of component parts of a large 
program are hashed. 

§ The strings are replaced with references to the common area. 
Find wordy sentences in a document. 


DICTION 
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# Finds all sentences that contain phrases from a data base of 
bad or wordy diction. 

# The user may supply his own pattern file. 

EXPLAIN Interactive thesaurus for the phrases found by diction. 

STYLE Analyze surface characteristics of a document. 

# Reports on 

readability 

sentence length and structure 
word length and usage 
verb type 
sentence openers 

# Options to locate sentences with certain characteristics. 


3.2. Document Formatting 

VTROFF Troff for raster printer/plotter. 

VF0NT1NF0Inspect and print out information about unix fonts. 


SOELB! 

FMT 


ME 


CHECKNR 


PT1 


Eliminate .so's from nroff input. 

Simple text formatter. 

# Produces an output with lines as close to 72 characters as pos¬ 
sible. 

# Spacing at the beginning of input lines and blank lines are 
preserved. 

Technical paper layout package for use with NROFF, TROFF and 
VTROFF. 

Check NROFF/TROFF files. 

# Knows about MS and ME macro packages. 

# Checks unknown commands. 

# Checks mismatched opening and closing delimiters in case of 

macros which always come in pairs 
font changes 
size changes 

Interpret a stream from the standard output of TROFF as it would 
act on the typesetter. 


4. Games 

FISH 

HANGMAN 

HANG 

TWINKLE 1 

TWINKLE2 

WORM 

WORMS 


Childrens’ card guessing game. 

Word guessing games. Uses the dictionary supplied with SPELL 

Milky way on the screen. 

Lead the worm to random points. 

Several worms running around on screen. 
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This document describes the text processin g facilities available on the UNIX? operating 
system via NROFF? and the '-me macro package. It is assumed that the reader already is gen* 
erally familiar with the UNIX operating system and a text editor such as ex. This is intended to 
be a casual introduction, and as such not ail material is covered. In particular, many variations 
and additional features of the —me macro package are not explained. For a complete discus¬ 
sion of this and other issues, see The —me Reference Manual and The NROFTTFROFF Reference 
Manual 

NROFF, a computer , program that runs on the UNIX operating system, reads an input file 
prepared by the user and outputs a formatted paper suitable for publication or framing. The 
input consists of text, or words to be printed, and requests, which give instructions to the 
* NROFF program telling how to format the printed copy. 

Section 1 describes the basics of text processing. Section 2 describes the basic requests. 
Section 3 introduces displays. Annotations, such as footnotes, are handled in secaon 4. The 
more complex requests which are. not discussed in section 2 are covered in section 5. Finally, 
section 6 di ^ ny * things you will' need to know if you want to typeset documents. If you are a 
novice, you probably won’t want to reed beyond section 4 until you have tried some of the 
basic features out. 

When you have your raw text ready, call the NROFF formatter by typing as a request to 
the UNIX shell; 

nroff —me —T type files 

where type describes the type of terminal you are outputting to. Common values are dtc for a 
DTC 300s (daisy-wheel type) printer and lpr for the line printer. If the —T flag is omitted, a 
“lowest common denominator” terminal is assumed; this is good for previewing output on 
most terminals. A complete description of options to the NROFF command can be found in 
Tne HR OFFTTR OFF Reference Manual 

The word argument is used in this manual to mean a word or number which appears on 
the same line as a request which modifies the meaning of that request. For example, the 
request 

jp 

•spaces one line, but 

-sp4 

spaces four lines. The number 4 is an argument to the .sp request which says to space four 
lines instead of one. Arguments are separated from the request and from each other by spaces. 


TUNIX. NROFF. and TROFF are TndetnartJ of Bell Laboratories 
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1. Basics o ( Text Processing 

The primary funcaon of NROFF is to collect words from input lines, fiU output lines 
with th os e words, justify the right hand margin by inserting extra spaces in the line, and out¬ 
put the result. For example, the input: 

Now is the time 
for all good men 
to come to the aid 
of their party. 

Four score and seven 
yean ago,— 

will be read, packed onto output lines, and justified to produce: 

Now is the time for all good men to come to the aid of their party. Four score and 
seven yean ago,— 

Sometimes you may want to start a new output line even though the line you are on is not 
yet full; for example, at the end of a paragraph. To do this you can cause a break, which 
starts a new output line. Some requests cause a break automatically, as do blank input lines 
and input lines beginning with a space. 

~ Not all input lines are text to be formatted Some of the input lines are requests which 
describe how to format the text Requests always have a period or an apostrophe (“*”) as 
the firet chaxscuex of the input line. 

The text formatter also does more complex things, such as automatically numbering 
pages, skipping over page folds, putting footnotes in the correct place, and so forth. 

. I can offer you a few hints for preparing text for input to NROFF. First, keep the 
input lines short. Short input lines are easier to edit, and NROFF will pack words onto 
longer lines for you anyhow. In keeping with this, it is helpful to begin a new line after 
every period comma, or phrase, since common corrections are to add or delete sentences or 
phrases. Second do not put spaces at the end of lines, since this can someti m es confuse 
the NROFF processor. Third do not hyphenate words at the end of lines (except words that 
should have hyphens in them, such as “mother-in-law”); NROFF is smart enough to 
hyphenate words for you as needed but is not smart enough to take hyphens out and join a 
word h ark together. Also, words such as “mother-in-law” should not be broken over a 
line, since th<^ you will get a space where not wanted such as “mother* in-law”. 

2. Basic Requests 

2.1. Paragraphs 

Paragraphs are begun by using the .pp request. For example, the input: 

•PP 

Now is the time for aO good men 
to come to the aid of their party. 

Four score and seven years ago,— 

produces a hianit line followed by an indented first line. The result is: 

Now is the time for ail good men to come to the aid of their party. Four 
score and seven years ago.— 

Notice tha t the sentences of the paragraphs must not begin with a space, since blank 
lines and lines begining with spaces cause a break. For example, if I had typed 
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•PP 

Now is the time for ail good men 
to come to the aid of their parry. 

Four score and seven years ago,... 

The output would be: 

Now is the time for all good men 

to come to the aid of their parry. Four score and seven years ago— 

A new line begins after the word “men 1 ' because the second line began with a space 
character. 

There are many fancier types of paragraphs, which will be described later. 

2.2. Headers and Footers 

Arbitrary headers and footers can be put at the top and bottom of every page. Two 
requests of the form .he tide and Jo tide define the titles to put at the head and the foot 
of every page, respectively. The titles are called three-pan titles, that is. there is a left- 
justified part, a centered part, and a right-justified pan. To separate these three parts the 
first character of title (whatever it may be) is used as a delimiter. Any character may be 
used, but backslash and double quote marks should be avoided. The percent sign is 
replaced by the current page number whenever found in the title. For example, the 
input: 

.he 

Jo 'Jane Jones"My Book' 

results in the page number centered at the top of each page, “Jane Jones” in the lower 
left comer, and “My Book” in the lower right comer. . 

2-3. Double Spacing 

NROFr will double space output text automatically if you use the request .Is 2, as 
is done in this section. You can revert to single spaced mode by typing .Is 1. 

2.4. Page Layout 

A number of requests allow you to change the way the printed copy looks, some¬ 
times called the layout of the output page. Most of these requests adjust the placing of 
“white space” (blank lines or spaces). In these explanations, charamers in italics should 
be replaced with values you wish to use; bold characters represent characters which 
should actually be typed. 

The .bp request starts a new page. 

The request jp N leaves /V lines of blank space. N can be omitted (meaning skip a 
single line) or can be of the form N\ (for N inches) or Nc (for N centimeters). For 
example, the input: 

.sp lJi 

My thoughts on the subject 

jp 

leaves one and a half inches of space, followed by the line “My thoughts on the sub¬ 
ject”. followed by a single blank line. 

The .In +.V request changes the amount of white space on the left of the page (the 
indent). The argument /V can be of the. form *f.V (meaning leave ;V spaces more than 
you are already leaving), — /V (meaning leave less than you do now), or just ;V (meaning 
leave exactly ;V spaces). N can be of the form .VI or ,Yc also. For exampie. the input: 
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initial text 
.in 5 

some text 
.in li 
more text 
.in -2c 
final text 

produces “some text” indented exactly five spaces from the left margin, “more text” 
indented five spaces plus one inch from the left margin (fifteen spaces on a pica type¬ 
writer), and “final text” indented five spaces plus one inch minus two centimeters from 
the margin. That is* the output is: 

initial text 

some text 

more text 

final text 

The .d +/V (temporary indent) request is used like .In +N when the indent 
should apply to one line only, after which it should revert to the previous indent. For 
example, the input; 

in U 
.ti 0 

Ware, James R. The Best of Confudus, 

Halcyon House, 1950. 

An excellent book containing translations of 
most of Confucius' most delightful sayings. 

A definite must for anyone interested in the early foundations 
of Chinese philosophy. 

produces; 

Ware, James R. The Best of Confucius, Halcyon House, 1950. An excellent book con¬ 
taining translations of most of Confudus’ most delightful sayings. A 
definite must for anyone interested in the early foundations of Chinese 
philosophy. 

Text lines can be centered by using the .ce request. The line after the .ce is cen¬ 
tered (horizontally) on the page. To center more than one line, use .ce S (where N is 
the number of lines to center), followed by the lines. If you want to center many 
lines but don’t want to count them, type: 

.ce 1000 
lines to center 
.ceO 

The .ce 0 request tells NROFF to center zero more lines, in other words, stop centering. 

All of these requests cause a break: that is, they always start a new line. If you 
want to start a new line without performing any other action, use .br. 

U. Underlining 

Text can be underlined using the .nl request. The .ni request causes the next 
input line to be underlined when output. You can underline multiple lines by stating a 
count of input lines to underline, followed by those lines (as with the .ce request). For 
example, the input: 

-ui 2 

Notice that these two input lines 
are underlined. 

will underline those eight words in NROFF. (In TROFF they will be set in italics.) 
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3. Displays 

Displays are sections of text to be set off from the body of the paper. Major quotes, 
tables, and figures are types of displays, as are all the examples used in this document. All 
displays except centered blocks are output single spaced. 

3-1. Major Quotes 

Major quotes, are quotes which are several lines long, and hence are set in from the 
rest of the text without quote marks around them. These can be generated using the 
commmands .(q and .)q to surround the quote. For example, the input: 

As Weizenbaum points out: 

M 

It is said that to explain, is to explain away. 

This maxim is nowhere so well fulfilled 
as in the areas of computer p rogr ammin g.-. 

•)q 

generates as output: 

As Weizenbaum points ouc 

It is said that to explain is to explain away. This maxim is nowhere so well fulfilled as in 
the areas of computer progra mmi n g .-. 

3.2. Lists 

A list is an indented, single spaced, unfilled display. Lists should be used when the 
material to be printed should not be filled and justified like normal text, such as columns 
of figures or the examples used in this paper. Lists are surrounded by the requests .(1 
and JL For example, type: 

Alternatives to avoid deadlock are: 

.a 

Lock in a specified order 
Detect deadlock and back out one process 
Lock all resources needed before p roceeding 
.)1 

will produce: 

Alternatives to avoid deadlock are: 

Lock in a specified order 

Detect deadlock and back out one process 

Lock all resources needed before proceeding 

3.3. Keeps 

A keep is a display of lines which are kept on a single page if possible. An example 
of where you would use a keep might be a diagram. Keeps differ from lists in that lists 
may be broken over a page boundary whereas keeps will not 

Blocks are the basic kind of keep. They begin with the request .(b and end with 
the request .)b. If there is not room on the current page for everything in the block, a 
new page is begun. This has the unpleasant effect of leaving blank space at the bottom 
of the page. When this is not appropriate, you can use the alternative, called /looting 
keeps. 

Floating keeps move relative to the text. Hence, they are good for thing s which will 
be referred to by name, such as “See figure 3”. A floating keep will appear at the bot* 

. tom of the current page if it will fit: otherwise, it will appear at the top of the next page. 
Floating keeps begin with the line .(z and end with the line .)z. For an example of a 
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floating ices?, see figure 1. The .hi request is- used to draw a horizontal line so that the 
figure stands out from the text. 

3.4. Fancier Displays 

Keeps and lists are normally collected in nofill mode, so that they are good for 
tables and such. If you want a display in fill mode (for text), type .(] F.(Throughout this 
section, comments applied to .(1 also apply to ,(b and .(z). This land of display will be 
indented from both margins. For example, the input: 

.(1 F 

And now boys and girls, 
a newer, bigger, better toy than ever before! 

Be the first on your block to have your own computer! 

Yes kids, you too can have one of these modem 
data processing devices. 

You too can produce beautifully formatted papers 
without even batting an eye! 

•)1 

will be output as: 

And now boys and girls, a newer, bigger, better toy than ever before! Be the 
first on your block to have your own computer! Yes kids, you too can have one 
of these modem data processing devices. You too can produce beautifully for¬ 
matted papers without even batting an eye! 

Lists and.blocks axe also normally indented (floating keeps are normally left 
justified). To get a left-justified list, type .(1 L. To get a list centered line-for-line, type 
. .(1 C. For example, to get a filled, left justified list, enter 

.(ILF 
text of block 

.)l 

The input: 

.0 

first line of unfilled display 

more lines 

•)l 

produces the indented text: 


.(z 

.hi 

Text of keep to be floated. 

•■sp 

.ce 

Figure 1. Example of a Floating Keep. 

-hi 

.)z 


Figure l. Example of a Floating Keep. 
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first Use of unfilled display 
more Uses 

Typing the character L after the .(1 request produces the left justified result: 

first Use of unfilled display 
more Uses 

Using C instead of L produces the line-at-a-time centered output: 

first Use of unfilled display 
more lines 

Sometimes it may be that you want to center several lines as a group, rather than 
centering them one Use at a time. To do this use centered blocks, which are surrounded 
by the requests ,(e and ,)c All the Uses are centered .as a unit, such that the longest 
Use is centered and the rest are Used up around that Use. Notice that Uses do not move 
relative to each other using centered blocks, whereas they do using the C argument to 
keeps. 

Centered blocks are not keeps, and may be used in conjunction with keeps. For 
example, to center a group of Uses as a unit and keep them on one page, use: 

.(bL 

.(c 

first Use of unfilled display 

more Uses 

.)c 

.Jb 

to produce: 

first Une of unfilled display 
more Uses 

If the block requests (,(b and .)b) had bees omitted the result would have been the 
same, but with no guarantee that the Uses of the centered block would have all been on 
one page. Note the use of the L argument to .(b; this causes the centered block to 
center within the entire Use rather than within the Use minus the indent. Also, the 
center requests must be nested inside the keep requests. 

4. Annotations 

There are a number of requests to save text for later printing. Footnotes are printed at 
the bottom of the current page. Delayed text is intended to be a variant form of footnote; 
the text is printed only when expUdtly called for. such as at the end of each chapter. 
Indexes are a type of delayed text having a tag (usually the page number) attached to eac h 
entry after a row of dots. Indexes are also saved until called for expUdtly. 

4.1. Footnotes 

Footnotes begin with the request ,(f and end with the request Jf. The current 
footnote number is maintained automatically, and can be used by typing \*", to produce 

a footnote number 1 . The number is automatically incremented after every footnote. For 
example, the input: 


'Like mis. 
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• (Q . . 

A man who is not upright 

and at the same time is presumptuous; 
one who is not diligent and at the same time is ignorant: 
one who is untruthful and at the same time is incompetent; 
such men I do not count among acquaintances.^" 

.(f 

V" James R. Ware, 

.ui 

The Best of Confucius, 

Halcyon House, 1950. 

Page 77. 

•)f 

.)q 

generates the result: 

A man who is not upright and at the same time is presumptuous; one who is not dill- 
u■ £samedme is ignoranq one who is untruthful and at the same ume a m- 

qanpetent; reori men I do not count among acquaintances. 1 
It is important that the footnote appears inside the quote, so that you can be sure that the 
footnote will appear on the same page as the quote. 

4.2. Delayed Teat 

Delayed text is very «»miiar to a footnote except that it is printed when called for 
explicitly. This allows a list of references to appear (for example) at the end of each 
chapter, as is the convention in some disciplines. Use \"# on delayed text instead of \ 
as on footnotes. 

If you are delayed text as your standard reference mechanism, you can stffl 
use footnotes, except that you may want to reference them with special characters^ 
rather than numbers. 

4_3. Indexes 

An “index” (actually more like a table of contents, since the entries are not sorted 
alphabetically) resembles delayed text, in that it is saved until called for. However, each 
entry has the page number (or some other tag) appended to the last line ot the index 

entry after a row of dots. 

Index entries begin with the request .(x and end with .)x. "Hie .)x request may 
have a argument, which is the value to print as the “page number . It defaults to the 
current page number. If the page number given is an underscore (* *_ ) no page number 
or line of dots is printed at alL To get the line of dots without a pagft number, type Jx 
which specifies an explicitly null page number. 

The .xp request prints the index. 

For example, the input: 


jjwnes R. Wwe. 7 m nt its ofConfuena. Halcyon House. 1950. Pa«e 77. 

*5uca u an uieri^. 
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.(x 

Sealing wax 

•)x 

.(x 

Cabbages and kings 
.)x _ 

.(x 

Why the sea is boiling "hot 

.)x 2 Ja 

.(x 

Whether pigs have wings 
.)x “ 

.(x 

This is a terribly long index entry, such as might be used 
for a list of illustrations, tables, or figures; I expea it to 
take at least two lines. 

.)x 

-XP 

generates: 


Sealing wax .-. . . 9 

Cabbages and kings 

Why the sea is boiling hot ---- ---, 2 . 5 a 

Whether pigs have wings -. , r —-. . 

This is a terribly long index entry, such as might be used for a list of illustra¬ 
tions, tables, or figures; I expea it to take at least two lines. .-. _ 9 


The .(x request may have a single character argument, specifying the “name” of 
the index; the normal index is x. Thus, several “indiries” may be maintained simul¬ 
taneously (such as a list of tables, table of contents, etc). 

Notice that the index must be printed at the end of the paper, rather tha n at the 
beginning where it will probably appear (as a table of contents); the pages ma y have to 
be physically rearranged after printing. 

5. Fancier Features 

A large number of fancier requests exist, notably requests to provide other sorts of 
paragraphs, numbered sections of the form 1 . 2-3 (such as used in this document), and mul¬ 
ticolumn output. 

5.1. More Paragraphs 

Paragraphs generally Stan with .a blank line and with the first line indented. It is 
possible to get left-justified block-style paragraphs by using .lp instead of .pp, as demon¬ 
strated by the next paragraph. 

Sometimes you want to use paragraphs that have the body indented, and the first line 
exdented (opposite of indented) with a label This can be done with the .ip request. A 
word specified on the same line as .ip is printed in the mar g in, and the body is lined up 
at a prespecified position (normally five spaces). For example, the input: 
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.ip one 

This is the first paragraph. 

Notice how the first line 
of the resulting paragraph lines up 
with the other lines in the paragraph, 
ip two 

And here we are at the second paragraph already. 

You may notice that the argument to .ip 

appears 

in the margin. 

•Ip 

We can continue text™ 
produces as output: 

one This is the first paragraph. Notice how the first line of the resulting paragraph lines 
up with the other lines in the paragraph. 

two And here we are at the second paragraph already. You may nonce that the argu¬ 
ment, to ip appears in the margin. 

We can continue text without starting a new inde nt e d paragraph by using the ip request. 

If you have spaces in the label of a ip request, you must use an “unpaddable 
space” instead of a regular space. This is typed as a back slash character (“\”) followed 
by a space. For example, to print the label “Part 1”, enter: 

ip Tart\ 1* 

If a label of an indented paragraph (that is, the argument to ip) is longer than the 
s p ac e allocated for the label, ip will begin a new line after the label. For example, the 
input: 

ip longlabel 

This paragraph had a long label. 

The first character of text on the first line 

will not line up with the text on second and subsequent lines, 

although they will line up with each other. 

will produce: 
longlabel 

This paragraph had a long label. The first character of text on the first line will not 
line up with the text on second and subsequent lines, although they will line up 
with each other. 

It is possible to change the size of the label by using a second argument which is 
the size of the label. For example, the above example could be done conecdy by saying: 

ip longlabel 10 

which will make the paragraph indent 10 spaces for this paragraph only. If you have 
man y paragraphs to indent all the same amount, use the number regisur ii. For example, 
to leave one inch of space for the label, type: 

nr ii li 

somewhere before the first call to .ip. Refer to the reference manual for more informa¬ 
tion. 

If .ip is used with no argument at ail no hanging tag will be printed. For exampie. 
the input: 
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.ip [a] 

This is the first paragraph of the example. 

We have seen this sort of example before. 

JP 

This paragraph is lined up with the previous paragraph, 
but it has no tag in the margin. 

produces as output: 

[a] This is the first paragraph of the example. We have seen this sort of example 
before. 

This paragraph is lined up with the previous paragraph, but it has'no tag in the 

marg in 

A special case of .ip is .np, which automatically numbers paragraphs sequentially 
from 1. The numbering is reset at the next .pp, .ip, or .sh (to be described in the next 
section) request. For example, the input: 

mp 

This is the first point, 
mp 

This is the second point. 

Points are just regular paragraphs 

which are given sequence numbers automatically 

by the Jip request. 

•PP 

This paragraph will reset numbering by mp. 

• mp 

For example. 

we have reverted to numbering from one now. 
generates: 

( 1 ) This is the first point. 

(2) This is the second point. Points are just regular paragraphs which are given 
sequence numbers automatically by the mp request. 

This paragraph will reset numbering by mp. 

(1) For example, we have reverted to numbering from one now. 

5 .2. Section Headings 

Section numbers (such as the ones used in this document) can be automatically 
generated nyng the ,ih request. You must tell .sh the depth of the section number and 
a section title. The depth specifies how many numbers are to appear (separated by 
decimal points) in the section number. For example, the section number 4.2~5 h 2 S a 
depth of three. 

Section numbers are incremented in a fairly intuitive fashion. If you add a number 
(increase the depth), the new number starts out at one. If you subtract section numbers 
(or keep the same number) the final number is incremented. For example, the input: 

.sh 1 "The Prepro ce s s or" 

_sh 2 "Basic Concepts’ 

.sh 2 "Control Inputs" 

.sh3 
.sh 3 

.sh 1 "Code Generation" 

_sb 3 

produces as output the result: 
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1. The Preprocessor 

1 .1. Basic Concepts 

1.2. Control Inputs 

1 . 2 . 1 . 

1.2JL 

2. Code Generation 

2 . 1 . 1 . 

You can specify the section number to begin by placing the secuon number after 
the section title, using spaces instead of dots. For example, the request: ■ 

„sh 3 'Another section" 7 3 4 

will begin the secuon numbered 7 J.4; all subsequent .sh requests will number relative 
to this number. 

There are more complex features which will cause each secuon to be indented pro* 
porconaily to the depth of the section. For example, if you enter 

jit si N 

n ch secuon will be indented by an amount M S must have a scaling factor attached, 
that is, it must be of the form ,Vx, where x is a character telling what units /V is in. 
Common values for x are i for inches, c for centimeters, and n for ens (the width of a 
single character). For example, to indent each section one-half inch, type: 

nr si Q-ii 

After this, sections will be indented by one-half inch per level of depth in the section 
number. For example, this document was produced using the request 

mr si 3n 

at the beginning of the input file, giving three spaces of indent per section depth. 

Section headers without automatically generated numbers can be done using: 

.uh Title’ 

which will do a section heading, but will put no number on the section. 

5 J. Parts of the Basic Paper 

There are some requests which assist in setting up papers. The .tp request initial¬ 
izes for a title page. There are no headers or footers on a title page, and unlike other 
pages you can space, down and leave blank space at the top. For example, a typical title 
page might appear as: 

•tP 

sp 2i 

.(1 C 

THE GROWTH OF TOENAJDLS 

IN UPPER PRIMATES 

-SP 

by 

•sp 

Frank N. Furter 
.)1 
.bp 

The request .th sets up the environment of the NROFF processor to do a thesis, 
using the rules established at Berkeley. It defines the correct headers and footers (a page 
number in the upper right hand comer only), sets the margins correcdy, and double 
spaces. 
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The .+c T request can be used to start chapters. Each chapter is automatically 
□umbered from one. and a heading is primed at the top of each chapter with the chapter 
□umber and the chapter name T. For example, to begin a chapter called "Conclusions”, 
use the request: 

.+c ’CONCLUSIONS’ 
which will produce, on a new page, the lines 

CHAPTER. 5 
CONCLUSIONS 

with appropriate sparing for a thesis. Also, the header is moved to the foot of the page 
on the first page of a chapter. Although the .+c request was not designed to work only 
with the .th request, it is tuned for the format acceptable for a PhD thesis at Berkeley. 

If the title parameter T is omitted from the .+c request, the result is a chapter with 
no beading. This can also be used at the beginning of a paper; for example, .+c was 
used to generate page one of this document. 

Although papers traditionally have the abstract, table of contents, and so forth at 
the front of the paper, it is more convenient to format and print them last when using 
NROFF. This is so that index entries can be collected and then printed for the table of 
contents (or whatever). At the end of the paper, issue the . + + P request, which begins 
the preliminary pan of the paper. After issuing this request, the .+c request will begin a 
prel iminar y section of the paper. Most notably, this prints the page number restarted 
from one in lower case Roman numbers. .+c may be used repeatedly to begin different 
parts of the front material for example, the abstract, the table of contents, acknowledg¬ 
ments, list of'illustrations, etc. The request .4-+ B may also be used to begin the 
bibliographic section at the end of the paper. For example, the paper might appear as 
outlined in figure 2. (In this figure, comments begin with the sequence \\) 

5.4. Iqnations and Tables 

Two special UNIX p rogr a ms exist to format special types of material. Eqn and 
neqn set equations for the phototypesetter and NROFF respectively. Tbl arranges to 
print extremely pretty tables in a variety of formats. This document will only describe 
the embellishments to the standard features; consult the reference manuals for those 
processors for a description of their use. 

The eqn and neqn programs are described fully in the document Typesetting 
Mathematics — Users' Guide by Brian W. Kemighan and Lorinda L. Cherry. Equations 
are centered, and are kept on one page. They are introduced by the .IQ request and ter¬ 
minated by the .IN request. 

The .IQ request may take an equation number as an optional argument, which is 
printed vertically centered on the right hand side of the equation. If the equation 
becomes too long it should be split between two lines. To do this, type: 

.EQ (eq 34) 

text of equation 34 

JENC 

JEQ 

continuation of equanon 34 

.EN 

The C on the .IN request specifies that the equation will be continued. 

The tbl program produces tables. It is fully described (including numerous exam¬ 
ples) in the document Tbl — A Program to Format Tables by M. E. Lesk. Tables begin 
with the .TS request and end with the .TI request. Tables are normally kept on a single 
page. If you have a table which is too big to fit on a single page, so that you know it win 
extend to several pages, begin the table with the request .TS H and put the request .TH 
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^ V set for thesis mode 

io "DRAFT* \* define footer for each page 

j_ \* begin title page 

’ (j q \* center a large block 

THE GROWTH OF TOENAILS 
IN UPPER. PRIMATES 
-SP 
by 
sq 

Frank Furter 

.)l 

,+c INTRODUCTION 
.(x t 

Introduction 

.)x 

text of chapter one_ 

,+c "NEXT CHAPTER* 

.(x t 

Next Chapter 

.)x 

text of chapter two 
,+c CONCLUSIONS 
.(k t 

Conclusions 

.)x 

text of chapter three 
.-r*r B 

.+c BIBLIOGRAPHY 
.(x t 

Bibliography 

.)x 

text of bibliography 

p \* begin preliminary material 

",+c TABLE OF CONTENTS" 

-X p t V print index *t’ collected above 

.+c PREFACE \* begin another preliminary section 

text of preface 


Figure 2. Outline of a Sample Paper 


\" end centered part 

\* begin chapter named "INTRODUCTION* 
V make an entry into index V 

\* end of Index entry 

\" begin another chapter 
\" enter into index *t’ again 


\* begin bibliographic information 
\* begin another 'chapter* 
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after the part of the table which you want duplicated at the top of every page chat the 
table is printed on. For example, a table definition for a long table might look like: 






USING NROFF AND -ME 


15 


.TS H 

css 

BOO. 

THE TABLE TITLE 
.TH 

tex: of the table 
.TE 

5-5. Two Column Output 

You can get two column output automatically by using the request -2c. This causes 
everything after it to be output in two-column form. The request .be will sun a new 
column; it differs from .bp in that .bp may leave a totally blank column when it starts a 
new page. To reven to single column output, use .lc. 

5.6. Defining Macros 

A macro is a collection of requests and text which may be used by suting a simple 
request Macros begin with the line .ie xr (where xr is the name of the macro to be 
defined) and end with the line consisting of two dots. After defining the macro, stating 
the line -rr is the same as suting ail the other lines. For example, to define a macro that 
spaces 3 lines and then centers the next input line, enter 

.deSS 
jp 3 
.ce 

and use it by typing: 

.SS 

Title Line 
(beginning of text) 

Macro names may be* one or two characters. In order to avoid conflicts with names 
in —me, always use upper case letters as names. The only names to avoid are TS. TH, 
TE. EQ, and EN. 

5.7. Annotations Inside Keeps 

Sometimes you may want to put a footnote or index entry inside a keep. For 
example, if you want to maintain a “list of figures” you will want to do something like: 

•(z 

.(c 

text of figure 

.)c 

.ce 

Figure 5. 

.(x f 
Figure 5 
.)x 
.)z 

which you may hope will give you a figure with a label and an entry in the index f 
(presumably a list of figures index). Unfortunately, the index entry is read and inter¬ 
preted when the keep is read, not when it is printed, so the page number in the index is 
likely to be wrong. The solution is to use the magic string \! at the beginning of all the 
lines dealing with the index. In other words, you should use: 
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.(2 

.(C 

Text of figure 

•)c 

.ce 

Figure 5. 

\!.(x f 
VFigure 5 
\!.)x 
•)z 

which will defer the processing of the index until the figure is output. This will guaran¬ 
tee that the page number in the index is co rrect. The same comments apply to blocks 
(with .(b and.)b) as well. 

6 . TROFF and the Photosetter 

With a little care, you can prepare documents that will print nicely on either a reguiar 
terminal or when phototypeset using the TROFF formatting program. 

6.1. Fonts 

A font is a style of type. There are three fonts that are available simultaneously. 
Times Roman, Times Italic, and Times Bold, plus the special math font. The normal 
font is Roman. Text which would be underlined in NROFF with the .al request is set in 
italics in TROFF. 

There are ways of switching between fonts. The requests .r. .1, and .b switch to 
Roman, italic, and bold fonts respecavely. You can set a single word in some font by 
typing (for example): 
i word 

which will set word in italics but does not affect the surrounding text. In NROFF, italic 
and bold text is underlined. 

Notice that if you are setting more than one word in whatever font, you must sur¬ 
round that word with double quote marks (*'*) so that it will appear to the NROFF pro¬ 
cessor as a single word. The quote marks will not appear in the formatted text. If you 
do want a quote mark to appear, you should quote the entire string (even if a single 
word), and use rwo quote marks where you want one to appear. For example, if you 
want to produce the text: 

* Master ConxroC 
in italics, you must type: 
i “"Master ControlNT" 

The \j produces a very narrow space so that the “1” does not overlap the quote sign in 
TROFF, like this: 

'Master Contror 

There are also several “pseudo-fonts” available. The input: 

.(b 

.u underlined 
.bi "bold italics" 

.bx "words in a box' 

.)b 


generates • 
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underlined 

bold, italics 

Iwords in a boxl 

In NROFF these ail just underline the text. Notice that pseudo font requests set only the 
single parameter in the pseudo font; ordinary font requests will begin setting ail text in 
the special font if you do not provide a parameter. No more than one word should 
appear with these three font requests in the middle of lines. This is because of the way 
TROFF justifies text. For example, if you were to issue the requests: 

.bi ’some bold italics’ 
and 

.bx ’words in a box* 

in the middle of a line TROFF would produce rnfg tmii iaa iiiss and I words in a boxi . 
which I think you will agree does not look good. 

The second parameter of all font requests is set in the original font. For example, 
the font request: 

.b bold face 

generates “bold” is bold font, but sets “face” is the font of the surrounding text, 
resulting is: 
boldface. 

To set the two words bold and face both is bold face, type: 

.b ’bold face’ 

You can mix fonts is a word by using the special sequence \c at the end of a line 
to indicate “continue text processing”; this allows input lines to be joined together 
without a space inberween them. For example, the input: 

.u under \c 
J italics. 

generates under italics, but if we had typed: 

.u under 
J italics 

the result would have been under italics as two words. 

6 .2. Point Sizes 

The photo typesetter supports different sizes of type, measured in points. The 
default point size is 10 points for most text, 3 points for footnotes. To change the 
pointsize, type: 
sz +jV 

where N is the size wanted in points. The vertical spacing (distance between the bottom 
of most letters (the baseline ) between adjacent lines) is set to be proportional to the type 
size. 

Warning: point si zes on the photo typesetter is a slow mechanical opera¬ 

tion. Size changes should be considered carefully. 

6 . 3 . Quotes 

It is conventional when using the typesetter to use pairs of grave and acute accents 
to generate double quotes, rather than the double quote character (*”). This is because 
it looks better to use grave and acute accents; for example, compare ’quote" to "quote”. 

In order to make quotes compatible between the typesetter and terminals, you may 
use the sequences \*(lq and \*(rq to sand for the left and right quote respecnveiy. 
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These both appear as * on most terminals, but are typeset as “ and ” respecuvely. For 
example, use: 

\*(lqSome things aren't true 
even, if they did happen.\*(rq 

to generate the result: 

“Some thrift aren’t true even if they did happen.” 

As a shorthand, the special font request: 

.q 'quoted, text* 

will generate “quoted text”. Nonce that you must surround the material to be quoted 
with double quote marks if it is more than one word. 
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This describes in extremely terse form the features of the -me macro package 

for version seven NROFF/TROFF. Some familiarity is assumed with those programs, 
specifically, the reader should understand breaks, fonts, pointsizes. the use and definition of 
number registers and strings, how to define macros, and s cal in g factors for ens, points, r’s 
(vertical line spaces), etc. 

t‘For a more casual introduction to text processing using NROFF, refer to the document 
Writing Papers with NROFF using —me. 

There are a number of macro parameters that may be adjusted. Fonts may be set to a 
fontfhumber only. In NROFF font 8 is underlined, and is set in bold font in TROFF (although 
font*3, bold in TROFF, is not underlined in NROFF). Font 0 is no font change: the font of the 
surrounding text is used instead. Notice that fonts 0 and 8 are “pseudo-fonts”; that is, they 
are by the macros. This means that although it is legal to set a font register to zero 

or it is not legal to use the es ca p e cha ract er form, such as: 

\f8 

All distances are in basic units, so it is nearly always necessary to use a scaling factor. For 
example, the request to set the paragraph indent to eight one-en spaces is: 

mr pi 8n 
and hot 

jit pi 8 

which would set the paragraph indent to eight basic units, or about 0.02 inch. Default parame¬ 
ter values are given in brackets in the remainder of this docu m e n t. 

Registers and strings of the form Sx may be used in expressions but should not be 
changed. Macros of the form Sx perform some function (as described) and may be redefined to 
change this function. This may be a sensitive operation; look at the body of the original macro 
before changing it. 

All in —me follow a rigid naming convention. The user may define number regis¬ 

ters, strings, and macros, provided that s/he uses single character upper case names or double 
names consisting of letters and digits, with at least one upper case letter. In no case 
should special characters be used in user-defined n a mes . 

On daisy wheel type printers in twelve pitch, the —rxl Hag can be stated to make lines 
default to one eighth inch (the normal spacing for a newline in twelve-pitch). This is normally 
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ao small for «sy tcndnbility. so me default is to space one suth inch. ' . 

Tils documentation was TROFFed on December K 1979 and applies tn version 1.1/M 
of the —me macros. 

L ^eCos are used to begin paragraphs. The standard paragraph macro is .pp; the 

others are all variants to be used for special purposes. 

_ - , tn ftn . of n,. paragraphing macros denned in this section or the .sfa macro 

(defined** the next session) initialize the ^Sne- 

S?MS formal of‘the P^eWably page length and header 

f£El Sr£s> ar£iot well denned and should be avoided. 


Jp 


•PP 


Jp Tl 


jip 


Beam left-justified paragraph. Centering and underlining are turned off 
if they were on, the font is set to \n(pf [ll the type size is set to \a(pp 
tlOpK and a \n(ps space is inserted before the paragrapn lOJSvin 
troFF lv or 0.5v in NROFF depending on device resoiuuonl. The 
5£nfis reset to \n(S [01 plus\n(po [01 unless theparagrapn is inside 
a display, (see .be). At least the first two lines of the paragrapn are 
kept together on a page. 

j nrw Jp, except that it puts \n(pi [5nl units of indent. This is the stan¬ 
dard paragraph macro. 

hvw ed paragraph with hanging tag. The body of the following para¬ 
graph is indented / spaces (or \n(ii (5nJ spaces if / a not speoned) 
more than a non-indented paragraph" (such as with .pp) is. The tide T 
is exdented (opposite of indented). The result is a paragraph with an 
even left edge and T printed in the margin. Any spaces in T must be 
unpaddable. If Twill not fit in the space provided, up will start a new 

line, 

A variant of ip which numbers paragraphs. Numbering^ reset after a 
iPu -PPb or uh. The current paragraph number is in \n(5p. 


, 5 b +iVr« b cdef 


i Section Headings 

Numbered atom arc simffia u> bcmdnpto Urn . section ™nib«b *«<»«£ 

callv generated for each one. The section numbers are of the form 1—-3- The depth of the 
to HTSuni of cumbers (sepamed by decimnl poind u> the secuou uumb«. 

Unnumbered recto hetows are similar, escept that oo number is attached to the heed- 

tom numbered section of depth K If Wis oiminj the current ttepth 
(maintained in the number register \n($0) is used. The vataes ot the 
individual parts of the section number are maintained in \n(Sl througn 
There is a \n(ss (lv] space before the section- T is printed as a 
Se” font \a(sf (81 md size \n(sp [lOpl. The “name” of the 
Son may be accessed via \*(Sn. If \n(si is non-zero, the base 
indent is set to \n(si times the section depth, and the secaon utte is 
exdented. (See .ba.) Also, an additional ixdent or \n(sol[01 is added to 
the secaon title (but not to the body of the section). The font is then 
set to the paragraph font, so that more information may occur on the 
line with the secuon number and title, .sb insures that there is enough 
room to print the section head plus the beginning ot a paragrapn (aoout 
3 lines total). If a through /are specified, the section number is set to 
that number rather than incremented automatically. If any on 
through / are a hyphen that number is not reset. If T is a single 
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.sx +/V 

.ah T 
Jp TBl V 


.SO TBS 


.a - .S6 


underscore then the section depth and numbering is reset, but 

the base indent is not reset and nothing is printed out. This is useful to 
automatically coordinate section numbers with chapter numbers. 

Go to section depth S [—1], but do not print the number and title, and 
do not increment the section number at level S. This has the effect of 
starting a new paragraph at level S. 

Unnumbered section beading. The title T is printed with the same 
rules for spacing, font, etc., as for .sh. 

Print section heading. May be redefined to get fancier headings. T is 
the title passed on the .sh or .oh line; B is the section number for this 
section, and S is the depth of this section. These parameters are not 
always present; in particular, ~sh passes all three, .ah passes only the 
first, and .sx passes three, but the first two are null strings. Care 
should be taken if this macro is redefined; it is quite complex and sub¬ 
tle. 

This macro is called automatically after every call to .Sp. It is normally 
undefined, but may be used to automatically put .every section title into 
the able of contents or for some similiar function. T is the section title 
for the section title which was just printed, B is the section number, 
and N is the section depth. 

Traps called just before printing that depth section. May be defined to 
(for example) give variable sparing before sections. These macros are 
called from .Sp, so if you redefine that macro you may lose this feature. 


3. Headers and Footers 

Headers and footers are put at the top and bottom of every page automatically. They are 
set ua font \n<tf (31 and size \n(t? [10p]. Each of the definitions apply as of the nexr page. 
Three-part titles must be quoted if there are two blanks adjacent anywhere in the title or more 
than eight blanks total. 

The sparing of headers and footers are controlled by three number registers. \n(hm [4v] 
is the distance from the top of the page to the top of the header. \n(fm (3v] is the distance 
from the bottom of the page to the bottom of the footer, \n(ttn [Tv] is the distance from the 
top of the page to the top of the text, and \n(bm [6v] is the distance from the bottom of the 
page to the bottom of the text (no minal ). The macros .ml, .m2, .m3, and .m4 are also sup¬ 
plied for companbOity with ROFF documents. 


.he VmV 
Jo T mr ’ 
.eh T mr 
.oh T mr 
M’Tmr 

.of T mr 
.hx 

.ml +jV 
.m2 -KV 
.m3 +/V 
.m4 -r/V 
.ep 


Define three-part header, to be printed on the top of every page. 

Define footer, to be printed ax the bottom of every page. 

Define header, to be printed at the top of every even-numbered page. 
Define header, to be printed at the top of every odd-numbered page. 

Define footer, to be printed at the bottom of every even-aumbered 
page. 

Define footer, to be printed at the bottom of every odd-numbered page. 
Suppress headers and footers on the next page. 

Set the space between the top of the page and the header [4v]. 

Set the space between the header and the first line of text [2v]. 

Set the space between the bottom of the text and the footer [2vj. 

Set the space between the footer and the bottom of the page [4v], 

End this page, but do not begin the next page. Useful for forcing out 
footnotes, but other than that hardly every used. Must be followed by 
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.Sh 


.sr 

•SH 


a .bp or the end of input. 

Called at every page to print the header. May be redenned to provide 
fancy (e 2 -, multi-line) headers, but doing so loses the function of the 
!eh, .oh, .ef, and .of requests, as well as the chapter-style utle 

feature of.+«. • 

Print footer, same comments apply as in .Sh. 

A normally undefined macro which is called at the top of each page 
(after outputing the header, initial saved floating keeps, etc.); in other 
words, this macro is called immediately before printing text on a page. 
It on be used for column, hea din gs and the like. 


4. Displays 

All displays except centered blocks and block quotes are proceeded and followed by an 
,,, \_/v, [same as \n(psl space. Quote spacing is stored in a separate register; centered 
blocks^have no default initial or trailing space. The-venial spacing of all displays except quotes 
and centered blocks is stored in register \n(SR instead of \n(3r 


.Q mf 


.)1 

.(q 


•)q 

.(b mf 


•)b 

.(z mf 


.)z 

.(c 


Begin list. T.i<n - are single spaced, u n fi l led text. If /is F, the list will 
be filled. If m (11 is I the list is indented by \n(bl (4al; if M the list is 
indented to the left margin; if L the list is left justified with respect to 
the text (different from M only if the base indent (stored in \n(5i and 
set with .ba) is not zero); and if C the list is centered on a line-by-Une 
The list is set in font \n(df (01. Must be matched by a .)L This 
macro is almost like .(b except that no attempt is made to keep the 
display on one page. 

End list. 

Begin major quote. These are single spaced, filled, moved in from the 
text on both sides by \n(qi (4nl, proceeded and followed by \a(qs 
\samc as \n(bsl space, and are set in point size \n(qp lone point 
smaller than surrounding text]. 

End major quote. 

Begin block. Blocks are a form of keep, where the text of a keep is 
kept together on one page if possible (keeps are useful for tables and 
figures which should not be broken over a page). If the block will not 
fit on the current page a new page is begun, unless that would lave 
more than \n(bt [0] white space at the bottom of the text. If \n(bt is 
zero the threshold feature is turned off. Blocks are not filled unless / 
is f' when they are filled. The block will be left-justified if m is L, 
j n T j » V »d by \n(bi [4nl if m is I or absent, centered (line-for-line) if m 
is C, and left justified to the margin (not to the base indent) if m is M. 
The’biock is set in font \n(df (01. 

End block. 

Begin floating keep. Like .(b except that the keep is floated 10 the bot¬ 
tom of the page or the top of the next page. Therefore, its position 
relative to the text changes. The floating keep is proceeded and fol¬ 
lowed by \n(zs [lv] space. Also, it defaults to mode M. 

End floating keep. 

Begin centered block. The next keep is centered as a block, rather than 
on a line-by-tine basis as with .(b C. This call may be nested inside 

keeps. 
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.)c 


End centered block. 


5. Annotations 
.(d 

Jd n 

•Pd 

.(f 


.)f n 

.(xj: 


.)x P A 


•Xp X 

6 . Columned Ontpnt 
2c +SN 


.lc 

•he 


7. Fonts and Sizes 
J2 +P 


Begin delayed text. Everything in the next keep is saved for output 
later with .pd. in a manner similar to footnotes. 

End delayed text. The delayed text number register \n<Sd and the 
associated siring \“# are incremented if \ a # has been referenced. 

Print delayed text. Everything diverted via . (d is printed and truncated. 
This might be used at the end of each chapter. 

Begin footnote. The text of the footnote is floated to the bottom of the 
page and set in font \n(ff [1] and size \n(fp (8pl. Each entry is pre¬ 
ceded by \n(fs [0.2v] space, is indented \n(fi [3nl on the first line, 
and is indented \n(fu [0] from the right margin. Footnotes line up 
underneath two columned output. If the text of the footnote will not 
all fit on one page it will be carried over to the next page. 

End footnote. The number register \n(Sf and the associated string \ mm 
are incremented if they have been referenced. 

The macro to output the footnote seperator. This macro may be 
redefined to give other size lines or other types of separators. 
Currently it draws a lJi line. 

Begin index entry. Index entries are saved in the index x [xl until 
called up with .xp. Each entry is preceeded by a \n(xs [0.2v] space. 
Each entry is “undented*' by \n(xu [OJi]; this register tells how far the 
page number extends into the right margin. 

End index entry. The index entry is finished with a row of dots with A 
[null] right justified on the last line (such as for an author’s name), fol¬ 
lowed by P [\n%l. If A is specified, P must be specified; \n% can be 
used to print the current page number. If P is an underscore, no page 
number and no row of dots are printed. 

Print index x [xl. The index is formated in the font, size, and so forth 
in effect at the time it is printed, rather than at the time it is collected. 


Enter two-column mode. The column separation is set to +S [4a, 0.5i 
in ACM mode] (saved in \n(Ss). The column width, calculated to fill 
the single column line length with both columns, is stored in \n(SL 
The current column is in \n(Sc You can test register \n(Sm [1] to see 
if you are in single column or double column mode. Actually, the 
request enters N (21 columned output. 

Revert to single-column mode. 

Begin column. This is like .bp except that it begins a new column on a 
new page only if necessary, rather than forcing a whole new page if 
there is another column left on the current page. 


The pointsize is set to P [lOp], and the line spacing is set proportion¬ 
ally. The ratio of line spacing to pointsize is stored in \n(Sr. The ratio 
used internally by displays and annotations is stored in \n(SR (although 
this is not used by -sz). 
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j WX 

.i tvx 


.b WX 
.rb WX 

.u WX 


A WX 
M WX 

.bx WX 


Set W in roman font, appending X in the previous font. To append 
different font requests, use X - \c If no parameters, change to roman 

font. 

Set W in italics, appending X in the previous font. If no parameters, 
change to italic font. Underlines in NROFF. 

Set W in bold font and append X in the previous font. If no parame¬ 
ters, switch to bold font. In NROFF, underlines. 

Set W in bold font and append X in the previous font. If no parame¬ 
ters, switch to bold font, .rb differs from .b in that .rb does not under¬ 
line in NROFF. 

Underline W and append X This is a true underlining, as opposed to 
the ol request, which changes to “underline font” (usually italics in 
TROFF). U won’t woric right if W is spread or broken (including 
hyphenated). In other words, it is safe in no nil mode only. 

Quote W and append X In NROFF this just surrounds W with double 
quote marks (**’), but in TROFF uses dimmed quotes. 

Set IK in bold italics and append X Actually, sets IK in italic and over- 
strikes once. Underlines in NROFF. It won’t work right if IK is spread 
or broken fotHudfag hyphenated). In other words, it is safe in nofill 

mode only. 

Sets IK in a box, with X appended. Underlines in NROFF. It won’t 
work right if IK is spread or broken (including hyphenated). In other 
words, it is safe in nofill mode only. 


8. Roff Support 
.ix +iV 
.bliY 

.pa +jV 
.ro 

JT 
.nl 
.n2 N 
«sk 


Indent, no break. Equivalent to 'in iV. 

Leave N contiguous white space, on the next page if not enough room 
on page. Equivalent to a .sp S inside a block. 

Equivalent to .bp. 

Set page number in roman numerals. Equivalent to .af % i. 

Set page number in arabic. Equivalent to .af Yt 1. 

Number lines in margin from one on each page. 

Number lines from iV, stop if ff m 0- 

Leave the next output page blank, except for headers and footers. This 
is used to leave space for a full-page diagram which is produced exter¬ 
nally and pasted in later. To get a partial-page paste-in display, say 
.rr iY, where (V is the amount of space to leave; this space will be out¬ 
put immediately if there is room, and will otherwise be output at the 
top of the next page. However, be warned: if jV is greater than the 
amount of available space on an empty page, no space will ever be out¬ 
put. 


9. Preprocessor Support 

EO m T Begin equation. The equation is centered if m is C or omitted. 

v indented \n(bi [4nl if m is I, and left justified if m is L. T is a title 

printed on the right margin next to the equation. See Typesetting 
Mathematics - User's Guide by Brian W. Kernighan and Lorinda L. 
Cherry. 
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.IN c 

.TS h 

.TH 

.TT 


10. Miscellaneous 

Jt 

.xi +N 
J1 +N 

.hi 

Jo 

11. Standard Papers 

.tp • 

.th 

.++ m H 


End equation. If c is C the equation must be continued by immediately 
following with another .IQ, the text of which can be centered along 
with this one. Otherwise, the equation is printed, always on one page, 
with \n(es [0.5v in TROFF, lv in NROFFl space above and below it. 

Table start. Tables are single spaced and kept on one page if possible. 
If you have a large table which will not fit on one page, use h - H and 
follow the header part (to be printed oq every page of the table) with a 
.TH. See Tbl — A P r o gr am to Format Tables by M. E. Lesk. 

With .TS H, ends the header portion of the table. 

Table end. Note that this table does not float, in fact, it is not even 
guaranteed to stay on one pegs if you use requests such as .sp inter* 
mixed with the text of the table. If you want it to float (or if you use 
requests inside the table), surround the entire table (including the .TS 
and .TI requests) with the requests .(z and ,)z. 


Reset tabs. Set to every OJi in TROFF and every O.Si in NROFF. 

Set the base indent to +N [01 (saved in \n(Si). All paragraphs, sec¬ 
tions, and displays come out indented by this amount. Titles and foot¬ 
notes are unaffected. The -sh request performs a .ba request if \n(si 
[0] is not zero, and sets the base indent to \n(si”\n(S0. 

Set the line length to .V [6.0i]. This differs from J1 because it only 
affects the current environment. 

Set line length in all environments to N [6.011. This should not be used 
after output has begun, and particularly not in two-columned output. 
The current line length is stored in \n(SL 

Draws a horizontal line the length of the page. This is useful inside 
floating keeps to differentiate between the text and the figure. 

This macro loads another set of macros (in /usr/Iib/me/local.me) 
which is intended to be a set of locally defined macros. These macros 
should all be of the form .*£ where X is any letter (upper or lower 
case) or digit. 


Begin title page. Spacing at the top of the page can occur, and headers 
and footers are supressed. Also, the page number is not incremented 
for this page. 

Set thesis mode. This defines the modes acceptable for a doctoral 
diss er tation at Berkeley. It double spaces, defines the header to be a 
single page number, and changes the margins to be 1.5 inch on the left 
and one inch on the top. .++ and .+c should be used with it. This 
macro must be stated before initialization, that is, before the first call of 
a paragraphing macro or ~sh. 

This request defines the section of the paper which we are entering. 
The section type is defined by m. C means that we are entering the 
chapter portion of the paper, A means that we are entering the appen¬ 
dix portion of the paper, P means that the material following should be 
the pr e li m i n a r y portion (abstract, table of contents, etc.) portion of the 
paper, AB means that we are entering the abstract (numbered indepen¬ 
dently from 1 in Arabic numerals), and B means that we are entering 
the bibliographic portion at the end of the paper. Also, the variants RC 
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and RA are allowed, which specify renumbering of pages from one at 
the beginning of each chapter or appendix, respectively. The H param¬ 
eter dehnes the new header. If there are any spaces in it, the entire 
header must be quoted. If you want the header to have the chapter 
number in it. Use the string \\\\n(ch. For example, to number appen¬ 
dixes A.1 etc., type .++ RA '"\\\\n(ch.%'. Each section (chapter, 
appendix, etc.) should be preceeded by the ,+c request It should be 
mentioned that it is easier when using TROFr to put the front material 
at the end of the paper, so that the table of contents can be collecmd 
and output; this mater ial can then be physically moved to the beginning 
of the paper. 

( + c t* Begin chapter with title T. The chapter number is maintained in \n(ch. 

This- register is incremented every time .+c is called with a parameter. 
The title and chapter number are printed by .Sc. The header is moved 
to the footer on the first page of each chapter. If T is omitted. .Sc is 
not called; this is useful for doing your own "title page” at the begin¬ 
ning of papers without a title page proper. .Sc calls .SC as a hook so 
that chapter titles can be inserted into a table of contents automatically. 
The footnote numbering is reset to one. 

fr. 7 * Print chapter n um ber (from \n(ch) and T. This macro can be 

redefined to your Hiring - It is defined by default to be acceptable for a 
PhD thesis at Berkeley. This macro calls SC, which can be defined to 
make index entries, or whatever. 

JSC K N T This macro is called by .St It is normally undefined, but can be used 

to automatically insert index entries, or whatever. AT is a keyword, 
either “Chapteri* or “Appendix” (depending on the .+4* mode); /Vis 
the chapter or appendix number, and 7* is the chapter or appendix title. 

2 c 4 ( y This macr o (short for .acm) sets up the NROFF environment for 

photo-ready papers as used by the ACM. This format is 25% larger, 
and has no headers or footers. The author’s name A is printed at the 
bottom of the page (but off the pan which will be printed in the confer¬ 
ence proceedings), together with the current page number and the total 
number of pages N. Additionally, this macro loads the file 
/usr/lib/me/acm.me, which may later be augmented with otter macros 
useful for printing papers for ACM conferences. I; should be noted 
that this macro will not work correctly in TROFF, since it sets the page 
len g th wider than the physical width of the phototypesetter roll. 


12. Predefined Strings 

\" Footnote number, actually \*(\n(SA"l. This macro is incremented 

after each call to .)f. 

Delayed text number. Actually (\n(Sdl. 

Superscript. This string gives upward movement and a change to a 
smaller point size if possible, otherwise it gives the left bracket charac¬ 
ter (T). Extra space is left above the line to allow room for the super¬ 
script. 

\*| Unsuperscript. Inverse to \"(. For example, to produce a superscript 

you might type x\*l2\“l, which will produce jr. 

\« < Subscript. Defaults to 4 < ’ if half-carriage motion not possible. 

space is left below the line to allow for the subscript. 

\*> Inverse to \*<. 


Extra 
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\*(dw 

\*(mo 

\-<td 


\*(lq 

\*<rq 

\— 


The day of the week, as a word. 

The month, as a word. 

Today’s date, directly printable. The date is of the form December 14. 
1979. Other forms of the date can be used by using \n(dy (the day of 
the month; for example. 14), \*(mo (as noted above) or \n(mo (the 
same, but as an ordinal number; for example, December is 12). and 
\n(yr (the last two digits of the current year). 

Left quote marks. Double quote in NROFF. 

Right quote. 

% em dash in TROFF; two hyphens in NROFF. 


13. Special Characters and Marks 

There are a number of special characters and diacritical marks (such as accents) available 
through —me. To reference these characters, you must call the macro .sc to define the charac¬ 
ters before using them. 

_ 5 c Define special characters and diacritical marks, as described in the 

remainder of this section. This macro must be stated before initializa¬ 
tion. 

The special characters available are listed below. 


Name 

Usage 

Example 


Acute accent 

r 

a\" 

a 

Grave accent 

\- 

e\- 

e 

Umlat 

\*: 

u\‘: 

u 

Tilde. 

\- 

n\~ 

n 

Caret 

\~ 

e\~ 

e 

Cedilla 

\*. 

c\*. 

c 

Czech 

\*v 

e\*v 

e 

Cirde 

\*0 

A\*0 

A 

There exists 

\‘(qe 


3 

For ail 

Wqa 


V 
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Text processing systems are now in heavy use in many companies to format 
documents. With many documents stored on line, it has become possible to use 
computers to study writing style itself and to help writers produce better writ¬ 
ten and more readable prose. The system of programs described here is an ini¬ 
tial step toward such help. It includes programs and data base designed to pro¬ 
duce a stylistic profile of writing at the word and sentence level. The system 
measures readability, sentence and word lenght, sentence type, word usage, and 
sentence openers. It also locates common examples of wordy phrasing and bad 
diction. The system is useful for evaluating a document's style, locating sen¬ 
tences that may be difficult to read or excessively wordy, and determining a 
particular writer’s style over several documents. 
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1. Introduction 

Computers have become important in the document preparation process, with programs to 
check for spelling errors and to format documents. As the amount of text stored on line 
increases, it becomes feasible and attractive to study writing style and to anempt to help the 
writer in producing readable documents. The system of writing tools described here is a first 
step toward such help. The system indudes programs and a data base to analyze writing style at 
the word and sentence level. We use the term “style" in this paper to describe the results of a 
writer’s particular choices among individual words and sentence forms. Although many judge* 
merits of style are subjective, particularly those of word choice, there are some objective meas¬ 
ures that experts agree lead to good style. Three programs have been written to measure some 
of the objectively definable characteristics of writing style and to identify some commoniy 
misused or unnecessary phrases. Although a document that conforms to the stylistic rules is 
not guaranteed to be coherent and readable, one that violates all of the rules is likely to be 
difficult or tedious to read. The pr ogr a m STYLE calculates readability, sentence length variabil¬ 
ity, sentence type, word usage and sentence openers at a rate of about 400 words per second on 
a PD PI 1/70 running the UMXt Operating System. It assumes that the sentences are well- 
formed. L e. that each sentence has a verb and that the subject and verb agree in number. 
DICTION identifies phrases that are either bad usage or unnecessarily wordy. EXPLAIN aca 
as a thesaurus for the phrases found by DICTION. Sections 2, 3, and 4 describe the programs: 
Section 5 gives the results on a cross-section of technical documents; Section 6 dismisses accu¬ 
racy and problems; Section 7 gives implementation details. 

2. STYLE 

The program STYLE reads a document and prints a summary of readability indices, sen¬ 
tence length and type, word usage, and sentence openers. It may also be used to locate all sen¬ 
tences in a document longer than a given length, of readability index higher than a given 
number, those containing a passive verb, or those beginning with an expletive. STYLE is 
based on the system for finding English word classes or parts of speech, PARTS (1]. PARTS is 
a set of pr og ra ms that uses a small dictionary (about 350 words) and suffix rules to partially 
assign word classes to English text. It then uses experimentally derived rules of word order to 
assign word classes to all words in the text with an accuracy of about 95%. Because PARTS 
uses only a small dictionary and general rules, it works on text about any subject, from physics 
to psychology. Style measures have been built into the output phase of the programs that make 
up PARTS. Some of the measures are simple counters of the word classes found by PARTS: 
many are more complicated. For example, the verb count is the total number of verb phrases. 
This includes phrases like: 


. tUXDC is i Trademark of Bell Laboratories. 
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has been going 
was only going 
to go 

each of which each counts as one verb. Figure 1 shows the output of STYLE run on a paper by 
Kernighan and Mashey about the UNIX programming environment [2]. 

programming environment 
readability grades: 

(Kincaid) 12J (auto) 12.8 (Coleman*Liau) 11.8 (Fiesch) 13.5 (46.3) 

sentence info: 

no. sent 335 no. wds 7419 

av sent leng 22.1 av word leng 4.91 

no. questions 0 no. imperatives 0 

no. nonfunc wds 4362 58.8% av leng 6.38 

shon sent «17) 35% (118) long sent 032) 16% (55) 

longest sent 32 wds at sent 174; shonest sent 1 wds at sent 117 

sentence types: 

simple 34% (114) complex 32% (108) 
compound 12% (41) compound-complex 21% (72) 

word usage: 

verb types as % of total verbs 
tobe 45% (373) aux 16% (133) inf 14% (114) 
passives as % of non-inf verbs 20% (144) 
types as % of total 

prep 10.8% (804) conj 3.5% (262) adv 4.8% (354) 
noun 26.7% (1983) adj 18.7% (1388) pron 5J% (393) 
nominalaations 2 % (155) 

sentence beginnings: 

subject opener, noun (63) pron (43) pos (0) adj (53) an (62) tot 67% 

' prep 12% (39) adv 9% (31) 

verb 0% (1) sub_conj 6% (20) conj 1% (5) 

expletives 4% (13) _ 


Figure 1 

As the example shows, STYLE output is in five parts. After a brief discussion of sentences, we' 
will describe the parts in order. 

2.1. What Is a sentence? 

Readers of documents have little trouble deciding where the sentences end. People don’t 
even have to stop and think about uses of the character *\” in constructions like 1.25. A. J. 
Jones. Ph.D., i. e«, or etc. . When a computer reads a document, finding the end of sentences 
is not as easy. First we must throw away the printer’s marks and formatting commands that 
litter the text in computer form. Then STYLE defines a sentence as a string of words ending in 
one of: 

i •) / 

The end marker “/.” may be used to indicate an imperative sentence. Imperative sentences 
that are not so marked are not identified as imperative. STYLE properly handles numbers with 
embedded decimal points and commas, strings of letters and numbers with embedded decimal 
points used for naming computer file names, and the common abbreviations listed in Appendix 
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1. Numbers that end sentences, like the preceding sentence, cause a sentence break if the next 
word begins with a capital letter. Initials only cause a sentence break if the next word begins 
with a capital and is found in the dictionary of funcuon words used by PARTS. So the string 

J. D. JONES 

does not cause a break, but the string 
— system H. The ... 

does. With these rules most sentences are broken at the proper place, although occasionally 
either two sentences are called one or a fragment is called a sentence. More on this later. 

12 . Readability Grades 

The first section of STYLE output consists of four readability indices. As Klare points 
out in [3] readability indices may be used to estimate the reading skills needed by the reader to 
understand a document. The readability indices reported by STYLE are based on measures of 
P»nf^n rg and word lengths. Although the indices may not measure whether the document is 
coherent and well organized, experience has shown that high indices seem to be indicators of 
stylistic difficulty. Documents with short sentences and short words have low scores; those with 
long sentences and many polysyllabic words have high scores. The 4 formulae reported are 
Kincaid Formula [4], Automated Readability Index [5], Coleman-Liau Formula [6] and a nor¬ 
malized version of Flesch Reading Ease Score (7J. The formulae differ b ec a u se they were 
experimentally derived using different texts and subject groups. We will discuss each of the 
formulae briefly; for a more detailed discussion the reader should see [3]. 

The Kincaid Formula, given by: 

Readin?Jjrade—\ 1.8 *syljxrj*d+ J9 **dsjerjent— 15.59 

was based on Navy training manuals that ranged in difficulty from 5.5 to 16J in reading grade 
level. .The score reported by this formula tends to be in the mid-range of the 4 scores. 
Bem us e it is based on adult training manuals rather than school book text, this formula is prob¬ 
ably the best one to apply to technical documents. 

The Automated Readability Index (ARI), based on text from grades 0 to 7, was derived 
to be easy to automate. The formula is: 

RcadingJ}rade—4.1\ Vetjxrjvd+J '*dsj>er_seni—21A2 

ARI tends to produce scores that are higher than Kincaid and Coleman-Liau but are usually 
slightly lower than Flesch. 

The Coleman-Liau Formula, based on text ranging in difficulty from .4 to 16J, is: 
ReadingjGrade—5.19 •tetjxrjvd— J m sentjKr_ 100_wdr-15.8 

Of the four formulae this one usually gives the lowest grade when applied to technical docu¬ 
ments. 

The last formula, the Flesch Reading Ease Score, is based on grade school text covering 
grades 3 to 12. The formula, given by: 

R«di/ig_Scorr-206.835-84.6 *ry/ _per_wd—l.Q\5 Vdj jxrjsent 

is usually reported in the range 0 (very difficult) to 100 (very easy). The score reported by 
STYLE is scaled to be comparable to the other formulas, except that the maximum grade level 
reported is set to 17. The Flesch score is usually the highest of the 4 scores on technical docu¬ 
ments. 

Coke (8] found that the Kincaid Formula is probably the best predictor for technical docu¬ 
ments; both ARI and Flesch tend to overestimate the difficulty, Coleman-Liau tend to underes¬ 
timate. On text in the range of grades 7 to 9 the four formulas tend to be about the same. On 
easy text the Coleman-Liau formula is probably preferred since it is reasonably accurate at the 
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lower grades and it is safer to present text that is a little too easy than a little too hard. 

If a document has particularly difficult technical content, especially if it indudes a lot of 
mathematics, it is probably best to make the text very easy to read. Le. a lower readability index 
by shortening the sentences and words. This will allow the reader to concentrate on the techni¬ 
cal content and not the long sentences. The user should remember that these indices are^ esti¬ 
mators; they should not be taken as absolute numbers. STYLE called with **—r number” will 
print all sentences with an Automated Readability Index equal to or greater than “number”. 

2_3. Sentence length and structure 

The next two sections of STYLE output deal with sentence length and structure. Almost 
all books on writing style or effective writing emp h a siz e the importance of variety in sentence 
length and structure for good writings Ewing’s first rule in discussing style in the book Writing 
for Resuia (91 is: 

“Vary the sentence structure and length of your sentences.” 

Leggett. Mead and Charvat break this rule into 3 in Prentice-Hall Handbook for Writers (101 as 
follows: 

“34a. Avoid the overuse of short simple, sentences.” 

“34b. Avoid the overuse of long compound sentences.” 

“34c. Use various sentence structures to avoid monotony and increase effectiveness.” 

Although experts agree that these rules are important, pot all writers follow them. Sample 
technical documents have been found with almost no sentence length or type variability. One 
document had 90% of its sentences about the same length as the average; another was made up 
almost entirely of simple sentences (80%). 

The output sections labeled “sentence info” and “sentence types” give both length and 
saucture measures. STYLE reports on the number and average length of both sentences and 
words, and number of questions and imperative sentences (those ending in “/.”). The meas¬ 
ures of non-function words are an attempt to look at the content words in the document. In 
F^ g i;<h non-function words are nouns, adjectives, adverbs, and non-auxiliary verbs; function 
words are prepositions, conjunctions, articles, and auxiliary verbs. Since most function words 
are short, they tend to lower the average word length. The average length of non-function 
words may be a more useful measure for comparing word choice of different writers than the 
total average word length. The percentages of short and long sentences measure sentence 
length variability. Short sentences are those at least 5 words less than the average; long sen¬ 
tences are those at least 10 words longer than the average. Last in the sentence information 
section is the length and location of the longest and shortest sentences. If the flag “—1 
number” is used^ STYLE will print all sentences longer than “number”. 

of the difficulties in dezlint with the many uses of commas and conjunctions in 
F n g t;<h, sentence type definitions vary slightly from those of standard textbooks, but still meas¬ 
ure the same constructional activity. 

1. A simple sentence has one verb and no dependent clause. 

2. A complex sentence has one independent clause and one dependent clause, each with one 
verb. Complex sentences are found by identifying sentences that contain either a subordi¬ 
nate conjunction or a clause beginning with words like “that” or “who”. The preceding 
sentence has such a clause. 

3. A compound sentence has more than one verb and no dependent clause. Sentences 
joined by “;” are also counted as compound. 

4. A compound-complex sentence has either several dependent clauses or one dependent 
clause and a compound verb in either the dependent or independent clause. 

Even using these broader definitions, simple sentences dominate many of the technical 
documents that have been tested, but the example in Figure 1 shows variety in both sentence 










structure and sentence length. 
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2.4. Word Usage 

The word usage measures are an attempt to identify some other constructional features of 
writing style. There are many different ways in English to say the same thing. The construc¬ 
tions differ from one another in the form of the words used. The following sentences all con¬ 
vey approximately the same meaning but differ in word usage* 


The cxio program is used to perform all communication between the systems. 
The cxio program performs all communications between the systems. 

The cxio program is used to communicate between the systems. 

The cxio program communicates between the systems. 

All communication between the systems is performed by the cxio program. 


The distribution of the parts of speech and verb constructions helps identify overuse of partic¬ 
ular constructions. Although the measures used by STYLE are crude, they do point out prob¬ 
lem areas. For each category, STYLE reports a percentage and a raw count. In addition to 
oolong it tiie percentage, the user may find" it useful to compare tiie raw count with the 
number of sentences. If, for exa mp le, the number of infinitives is aimn« equal to the number 
of sentences, then many of the sentences in the document are constructed like the first and 
third in the preceding example. The user may want to transform some of these sentences into 
another form. Some of the implications of the word usage measures are disrj ssf d below. 

Verbs are measured in several different ways to try to determine what types of verb construc¬ 
tions are most frequent in the document. Technical writing tends to contain many passive 
verb constructions and other usage of the verb “to be”. The category of verbs labeled 
“tobe" measures both passives and sentences of the form: 


subject lobe predicate 


In counting verbs, whole verb phrases are counted as one verb. Verb phrases containing 
auxiliary verbs are counted in the category “aux”. The verb phrases counted here are 
those whose tense is. not simple present or simple past. It might eventually be useful to 
do more detailed measures of verb tense or mood. Infiniti ve are listed as “inf’. The 
percentages reported for these three categories are based on the total number of verb 
phrases found. These categories are not mutually exclusive; they cannot be added, since 
for example. *no be going” counts as both “tobe" and "inf”. Use of these three types of 
verb constructions varies significantly among authors. 


STYLE reports passive verbs as a percentage of the finite verbs in the document. Most 
style books warn against the overuse of passive verbs. Coleman (111 has shown that sen¬ 
tences with active verbs are easier to leant than those wjth passive verbs. Although the 
inverted object-subject order of the passive voice seems to emphasize the object 
Coleman’s experiments showed that there is little difference in retention by word position. 
He also showed that the direct object of an active verb is retained better than the subject 
of a passive verb. These experiments support the advice of the style books suggesting 
that writers should try to use active verbs wherever possible. The flag *‘-p" causes 
STYLE to print all sentences containing passive verbs. 

Pronouns add cohesiveness and connectivity to a document by providing back-reference. They 
are often a short-hand notation for something previously mentioned, and therefore con¬ 
nect the sentence containing the pronoun with the word to which the pronoun refers. 
Although there are other mechanisms for such connections, documents with no pronouns 
tend to be wordy and to have little connectivity. 
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Adverbs can provide transition between sentences and order in time and space. In performing 
these functions, adverbs, like pronouns, provide connectivity and cohesiveness. 

Conjunctions provide parallelism in a document by connecting two or more equal units. These 
units may be whole sentences, verb phrases, nouns, adjectives, or prepositional phrases. 
The compound and compound-complex sentences reported under sentence type are paral¬ 
lel structures. Other uses of parallel structures are indicated by the degree that the 
number of conjunctions reported under word usage exceeds the compound sentence 
measures. 

: Souns and Adjeaives. A ratio of nouns to adjectives near unity may indicate the over-use of 
modifiers. Some technical writers qualify every noun with one or more adjectives. 
Qualifiers in phrases like “simple linear single-link network model’* often lend more 
obscurity than precision to a text. 

tfominalaarions are verbs that are changed to nouns by adding one of the suffixes “meat”, 
“ance”, “ence”, or “ion”. Examples are accomplishment, admittance, adherence, and 
abbreviation. When a. writer transforms a nominalized sentence to a aon-nominalized 
sentence, she/he increases the effectiveness of the sentence in several ways. The noun 
becomes an active verb and frequently one complicated clause becomes two shorter 
clauses. For example. 

Their inclusion of this provision is admission of the importance of the system. 
When they included this provision, they admitted the importance of the system. 

Coleman found thai the transformed sentences were easier to learn, even when the 
transformation produced sentences that were slightly longer, provided the transformation 
broke one clause into two. Writers who find their document contains many nominaliza- 
tions may want to transform some of the sentences to use active verbs. 

U. Sentence openers 

Another agreed upon principle of style is variety in sentence openers. Because STYLE 
determines the type of sentence opener by looking at the pan of speech of the first word in the 
sentence, the sentences counted under the heading “subject opener” may not all really begin 
with the subject. However, a large percentage of sentences in this category still indicates lack 
of variety in sentence openers. Other sentence opener measures help the user determine if 
there are transitions between sentences and where the subordination occurs. Adverbs and con- 
junctions at the beginning of sentences are mechanisms for transition between sentences. A 
pronoun at the beginning shows a link to something previously mentioned and indicates con¬ 
nectivity. 

The location of subordination can be determined by comparing the number of sentences 
that begin with a subordinator with the number of sentences with complex clauses. If few sen¬ 
tences stan with subordinate conjunctions then the subordination is embedded or at the end of 
the complex sentences. For variety the writer may want to transform some sentences to have 
leading subordination. 

The last category of openers, expletives, is commonly overworked in technical writing. 
Expletives are the words “it” and “there”, usually with the verb “to be”, in constructions 
where the subject follows the verb. For example. 

There are three streets used by the traffic. 

There are too many users on this system. 

This construction tends to emphasize the object rather than the subject of the sentence. The 
flag “—e” will cause STYLE to prim all sentences that begin with an expletive. 
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3. DICTION 

The pr ogra m DICTION prims ail sentences in a document containing phrases that are 
either frequently misused or indicate wordiness. The program, an extension of Aho’s FGRJE? 
(12] string matching program, takes as input a file of phrases or patterns to be matched and a 
file of text to be searched. A data base of about 450 phrases has been compiled as a default 
patient file for DICTION. Before attempting to locate phrases, the program maps upper case 
letters to lower case and substitutes blanks for punauation. Sentence boundaries were deemed 
less critical in DICTION than in STYLE, so abbreviations and other uses of the character 
are not treated specially. DICTION brackets all pattern matches in a sentence with the charac¬ 
ters “]” . Although many of the phrases in the default data base are correct in some con¬ 
texts. in others they indicate wordiness. Some examples of the phrases and suggested alterna¬ 
tives are: 


Phrase 

Alternative 

a large number of 

many 

arrive ax a decision 

decide 

collect together 

coilea 

for this reason 

so 

pertaining to 

about 

through the use of 

by or with 

utilize 

use 

with the exception of 

except 


Appendix 2 com^ns a complete list of the default file. Some of the entries are short forms of 
problem phrases. For example, the phrase “the fact” is found in all of the following and is 
sufficient to point out the wordiness to the user 


Phrase 

Alternative 

accounted for by the fact that 

caused by 

an example of this is the fact that 

thus 

based on the fan that 

because 

despite the fact that 

although 

due to the fact that 

because 

in light of the fan that 

because 

in view of the fan that 

since 

notwithstanding the fan that 

although 


Entries in Appendix 2 preceded by are not matched. See Section 7 for details on the use 
of 

The user may supply her/his own pattern file with the flag “ — f patfile”. In this case the 
default file wifi be loaded first, followed by the user file. This mechanism allows users to 
suppress patterns contained in the default file or to indude their own pet peeves that are not in 
the default file. The Hag “—n” will exdude the default file altogether. In constructing a pat¬ 
tern file, hianfc* should be used before and after each phrase to avoid matching substrings in 
words. For example, to find all occurrences of the word “the”, the pattern “ the ” should be 
u sed The bla nfc? cause only the word “the” to be matched and not the string “the” in words 
like there, other, and therefore. One side effect of surrounding the words with blanks is that 
when two phrases occur without intervening words, only the first will be matched. 

4. EXPLAIN 

The last program. EXPLAIN, is an interactive thesaurus for phrases found by. DICTION. 
The user types one of the phrases bracketed by DICTION and EXPLAIN responds with sug¬ 
gested substitutions for the phrase that will improve the diction of the document. 
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Table 1 

Text Statistics on 20 Technical Documents 



variable 

minimum 

maximum 

mean 

standard deviation 

Readability 

Kincaid 

9.5 

16.9 

13.3 

12 


automated 

9.0 

17.4 

13J 

15 


Cole-Liau 

10.0 

16.0 

117 

1.8 


Flesdt 

8.9 

17.0 

14.4 

12 

sentence info. 

av sent length 

15.5 

30.3 

21.6 

4.0 


av word length 

4.61 

5.63 

5.08 

.29 


av Qonfuncrion length 

5.72 

7J0 

6.52 

.45 


short sent 

23% 

46% 

33% 

5.9 


long sent 

7% 

20% 

14% 

2.9 

sentence types 

simple 

• 31% 

71% 

49% 

11.4 


complex 

19% 

50% 

33% 

8.3 


compound 

2% 

14% 

7% 

3.3 

• 

compound-complex 

2% 

19% 

10% 

4.3 . 

verb types 

tobe 

26% 

64% 

44.7% 

10.3 


auxiliary 

10% 

40% 

21% 

8.7 


infinitives 

3% 

24% 

15.1% 

4.8 


passives 

12% 

50% 

29% 

9.3 

word usage 

prepositions 

10.1% 

15.0% 

113% 

1.6 


conjunction 

1.8% 

4.8% 

3.4% 

.9 


adverbs 

1.2% 

5.0% 

3.4% 

1.0 


nouns 

23.6% 

31.6% 

27.8% 

1.7 


adjectives 

15.4% 

27.1% 

21.1% 

3.4 


pronouns 

1.2% 

8.4% 

15% 

1.1 


nominal izations 

2% 

5% 

3.3% 

.3 

sentence openers 

prepositions 

6% 

19% 

12% 

3.4 


adverbs 

0% 

20% 

9% 

4.6 


subject 

56% 

85% 

70% 

8.0 


verbs 

0% ' 

4% 

1% 

1.0 


subordinating conj 

1% 

12% 

5% 

17 


conjuncnons 

0% 

4% 

0% 

1.5 


expletives 

0% 

6% 

2% 

1.7 


5. Results 
5.1. STYLE 

To get baseline statistics and check the program’s accuracy, we ran STYLE on 20 technical 
documents. There were a total of 3237 sentences in the sample. The shortest document was 
67 sentences long; the longest 339 sentences. The documents covered a wide range of subject 
matter, including theoretical computing, physics, psychology, engineering, and affirmative 
action. Table 1 gives the range, median, and standard deviation of the various style measures. 
As you will note most of the measurements have a fairly wide range of values across the sam¬ 
ple documents. 

As a comparison. Table 2 gives the median results for two different technical authors, a 
sample of instrucaonai material, and a sample of the Federalist Papers. The two authors show 
similar styles,' although author 2 uses somewhat shorter sentences and longer words than author 
1. Author 1 uses all types of sentences, while author 2 prefers simple and complex sentences, 
using few compound or compound-complex sentences. The other major difference in the styles 
of these authors is the location of subordination. Author 1 seems to prefer embedded or trail¬ 
ing subordination, while author 2 begins many sentences with the subordinate clause. The 
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documents tested for both authors 1 and 2 were technical documents, written for a technical 
audience. The instructional documents, which are written for craftspeople, vary surprisingly lit¬ 
tle from the two technical samples. The sentences and words are a little longer, and they con¬ 
tain many passive and auxiliary verbs, few adverbs, and almost no pronouns. The instructional 
documents contain many imperative sentences, so there are many sentence with verb openers. 
The sample of Federalist Papers contrasts with the other samples in almost every way. 


Table 2 

Text Statistics on Single Authors 



variable 

author 1 

author 2 

inst. 

FED 

readability 

Kincaid 

11.0 

10.3 

10.8 

16.3 


automated 

11.0 

10J 

11.9 

17.8 


Coleman*Liau 

9J 

10.1 

10.2 

113 


Flesch 

10J 

10.7 

10.1 

15.0 

sentence info 

av sent length 

22.64 

19.61 

2178 

31.85 


av word length 

4.47 

4.66 

4.65 

4.95 


av nonfuncnon length 

5.64 

5.92 

6.04 

6.87 


short sent 

35% 

43% 

35% 

40% 


long sent 

18% 

15% 

16% 

21% 

sentence types 

simple 

36% 

43% 

40% 

31% 


complex 

34% 

41% 

37% 

34% 


compound 

13% 

7% 

4% 

10% 


compound*compiex 

16% 

8% 

14% 

25% 

verb type 

to be 

42% 

43% 

45% 

37% 


auxiliary 

17% 

19% 

32% 

32% 


infinitives 

17% 

15% 

12% 

21% 


passives 

20% 

19% 

36% 

20% 

word usage 

prepositions 

10.0% 

10.8% 

113% 

15.9% 


conjunctions 

3.2% 

14% 

3.9% 

3.4% 


adverbs 

5.05% 

4.6% 

3.5% 

3.7% 


nouns 

27.7% 

26.5% 

29.1% 

24.9% 


adjectives 

17.0% • 

19.0% 

15.4% 

114% 


pronouns 

. 5J% 

4.3% 

11% 

6.5% 


nominaiizations 

1% 

2% 

2% 

3% 

sentence openers 

prepositions 

11% 

14% 

6% 

5% 


adverbs 

9% 

9% 

6% 

4% 


subject 

65% 

59% 

54% 

66% 


verb 

3% 

2% 

14% 

2% 


subordinating coqj 

8% 

14% 

11% 

3% 


conjunction 

1% 

0% 

0% 

3% 


expletives 

. 3% 

3% 

0% 

3% 


5.2. DICTION 

In the few weeks that DICTION has been available to users about 35,000 sentences have 
been run with about 5,000 string matches. The authors using the pr ogr a m seem to make the 
suggested changes about 50*75% of the time. To date, almost 200 of the 450 strings in the 
default file have been matched. Although most of these phrases are valid and correct in some 
contexts, the 50*75% change rate seems to show that the phrases are used much more often 
than concise diction warrants. 









6. Accuracy 

6.1. Sentence Identification 

The correctness of the STYLE output on the 20 document sample was checked in detail. 
STYLE misidentined 129 sentence fragments as sentences and incorrectly joined two or more 
sentences 75 times in the 32S7 sentence sample. The problems were usually because of non¬ 
standard formatting commands, unknown abbreviations, or lists of non-sentences. An impossi¬ 
bly long sentence found as the longest sentence in the document usually is the resuit of a long 
list of non-sentences. 

6.2. Sentence Types 

Style correctly identified sentence type on 86.5% of the sentences in the sample. The type 
distribution of the sentences was 52_5% simple, 29.9% complex. 8.5% compound and 9% 
compound-complex. The p r ogram reported 49.5% simple, 31.9% complex. 8% compound and 
10.4% compound-complex. Looking at the errors on the individual documents, the number of 
simple sentences was under-reported by about 4% and the complex and compound-complex 
were over-reported by 3% and 2%, respectively. The following matrix shows the programs out¬ 
put vs. the actual sentence type. 




Program Results 





simple 

complex 

compound 

comp-complex 

Acmai 

simple 

1566 

132 

49 

17 

Sentence 

complex 

47 

892 

6 

65 

Type 

compound 

40 

6 

207 

23 


comp-complex 

0 

52 

5 

249 


. The system’s inability to find imperative sentences seems to have little effect on most of 
the style statistics. A document with half of its sentences imperative was run. with and without 
the imperative end marker. The results were identical except for the expected errors of not 
finding verbs as sentence openers, not counting the imperative sentences, and a slight 
difference (1%) in the number of nouns and adjectives reported. 

6.3. Word Usage 

The accuracy of identifying word types reflects that of PARTS, which is about 95% 
correct. The largest source of confusion is between nouns and adjectives. The verb counts 
were checked on about 20 sentences from each document and found to be about 98% correct. 

7. Technical Details 

7.1. Finding Sentences 

The formatting commands embedded in the text increase the difficulty of finding sen¬ 
tences. Not all text in a document is in sentence form; there are headings, tables, equations 
and lists, for example. Headings like “Finding Sentences” above should be discarded, not 
attached to the next sentence. However, since many of the documents are formatted to be 
phototypeset, and contain font changes, which usually operate on the most important words in 
the document, discarding all formatting commands is not correct. To improve the programs' 
ability to find sentence boundaries, the deformatting program. DER0F7 [13]. has been given 
some knowledge of the formatting packages used on the UTdX operating system. DEROFF will 
now do the following: 

1. Suppress all formatting macros that are used for titles. .headings, author’s name. etc. 
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1 Suppress the arguments to the macros for titles, headings, author’s name. etc. 

3. Suppress displays, tables, footnotes and text that is centered or in no-fill mode. 

4. Substitute a place holder for equations and check for hidden end markers. The place 
holder is necessary because many typists and authors use the equation setter to change 
fonts on important words. For this reason, header files containing the definition of the 
EQN delimiters must also be included as input to STYLE. End markers are often bidden 
when an equation ends a sentence and the period is typed inside the EQN delimiters. 

5. Add a *.* after lists. If the flag —ml is also used, all lists are suppressed. This is a 
separate flag because of the variety of ways the list macros are used. Often, lists are sen¬ 
tences that should be included in the analysis. The user must determine how lists are 
used in the document to be analyzed. 

Both STYLE and DICTION call DEROFF before they look at the text. The user should 
supply the —ml flag if the document contains many lists of non-sentences that should be 
skipped. 

7.2. Details of DICTION 

. The program DICTION is based on the string matching program FGREP. FGRE? takes 
as input a file of patterns to be matched and a file to be searched and outputs each line that 
contains any of the patterns with no indication of which pattern was matched. The following 
chang es- have been added to FORE?*. 

1. The basic unit that DICTION operates on is a sentence rather than a line. Each sentence 
that contains one of the patterns is output. 

L Upper case letters are mapped to lower case. 

3. Punctuation is replaced by blanks. 

4 All pattern matches in the sentence are found and surrounded with “1” . 

5. • A method for suppressing a string match has been added. Any pattern that begins with 
* win Q ot be matched. Because the matching algorithm finds the longest substring, the 
suppression of a match allows words in some correct contexts not to be matched while 
allowing the word in another context to be found. For example, the word “which” is 
often incorrectly used instead of “that” in restrictive clauses. However, “which” is usu¬ 
ally correct when prec ed ed by a preposition or The default pattern file suppresses 
the match of the common prepositions or a double blank followed by “which” and there¬ 
fore matches only the suspect uses. The double blank accounts for the replaced comma. 

8. Conclusions 

A system of writing tools that measure some of the objective characteristics of writing 
style has been developed. The tools are sufficiently general that they may be applied to docu¬ 
ments on any subject with equal accuracy. Although the measurements are only of the surface 
structure of the text, they do point out problem areas. In addition to helping writers produce 
better documents, these p ro gra ms may be useful for studying the writing process and finding 
other formulae for measuring readability. 
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Introduction 

This catalog gives samples of the various fonts available at Berkeley using 
vtroff on our Versatec and Yarian. We have them working 4 pages across in a 36 
inch Versatec, and rotated 90 degrees on a Benson-Varian 11 inch plotter. The 
same software should be adaptable to an 11 inch Versatec, and in fact is running 
at several other sites, however, not having one here. It is n't part of this distribu¬ 
tion. Such a driver is available from Tom Ferrtn at UCSF. 

To use these fonts: 

(1) Hershey. This is the default font. The Hershey font is currently the only 
complete font, with all 16 point si2es and all the special characters troff 
knows about. To get It, use vtroff directly. To illustrate this with the —ms 
macro package: 

vtrofZ -ms papermr 

(2) Fonts with roman, italic, and bold, such as nonie. You can load all three 
fonts with, for example: 

vtroff -F nonie -ms papermr 

To get Just one of these fonts, use (3) below, appending s. .L or .b to the 
font name to specify which font you want mounted. e.g., to get italics in 
delegate, 

vtroff -2 delegate.! -ms paperjar 

(3) To get a font without a complete set, choose which* font (1. 2. or 3) you want 
replaced by the chosen font. For example, to use boeklin as though it were 
bold, since font 3 is bold, use: 

vtr of f —3 hocklln -ms paper jxt 

1 

To switch between fonts in troff. use 
Jt3 

to switch to font 3. for example, or use 
\f3worffvfl 

to switch within a line. For more information see the Nroff/Trofi Users Manual. 

Special note: troff thinks it is talking to a CAT phototypesetter. Thus, it 
does all sorts of strange things, such as enforcing restrictions like 7.34 inches 
martmum width. 4 fonts, a certain 16 point sixes, proportional spacing by point 
size, etc. 

In particular, the following glyphs will always be taken from the special 
font, no matter what font you are using at the time: 

• O. #, ". # . *,<,>, N. {. }. -. -. and- 

This may explain what are otherwise surprising results in some of the subse¬ 
quent pages. 

In addition, the following Greek letters have been decreed by troff as look¬ 
ing so much like their Roman counterparts that the Raman version, (font 1) is 
always printed, no matter what font is mounted on font 1 at the time: 

A. B. £. Z. H. I. K. H. N. 0, P. T. X. 

(See table H in the back of the Nrofl/Troff Users's Manual for details about what 
glyphs are in each font and how to generate the special glyphs.) 
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API FONT, 10 POINT ONLY 
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•Baskerville font, roman, lbcld, Italic, 12 point only (Called Easier’ on lineO 


ABCDE FCHIJ KLMNO PQRST UVWXYZ abcde fghij klmno pqrst uvwxyx 01234 £5783 

If time be of all things the most predcus, wasdng time must be, as Poor Richard ays, the greatest 
prodigality; sines, a he elsewhere tells us, lost time is neve found again; and what w« tail time 
mough, always proves little enough; Let us then up and be doing, and doing to the purpose; so by 
diligence «n*n we do more with less perplexity. 

A3CDE FGH1J KLMNO PQ,RST UVWXYZ abcde fghij Umno pjrst uowxyz 01234 56789 
i M # j i (t * () :*• - / / H • - —\ I © *; ♦ / * -> • < 

Ifttmt be of ell things the nest precious, wasting ttsne waist be, as Peer Richard says, the gr taxis: 
prodigality; sines, as hs elsewhere tells us, lest ttms is never fenmd again; end what ws cell time 
enough, always proves little enough: Let us then up end be doing, end doing to the purpose; so by 
diligence shell we do mere with less perplexity. 

ABCDE FGHIJ KLMNO PQRST UVWXYZ abode fghij klmno pqrst urwryi 01234 5S789 

l" # S X le ’():•• * U { J ~ ~ —\ 1 ® *1 • / ? . > . < 

If time be of all things the most precious, wasting time must be, as Poor Richard ays, the 
greatest prodigality; since, as be elsewhere tells us, lost time is never fwnd again; and what we 
«n time enough, always proves little enough: Lex us then up and be doing, and doing to the 
purpose; so by diligence shall we do more with less perplexity. 



Bociiiin Iont.14 and 2S point only. 


14 point 

FtBCBI FSBT3 KLHB0 PQR.5T tlWXTX abode Ighi] hlmno pqrst uvwxys 
01234 55723 

•* C ) /? .. 

H time be ol all things the most precious. wasting time must be. as Poor 
Richard says, the greatest prodigality: since* as ne elsewhere tells us. 
lost time is nearer Icund again: and what we call time enough, always 
proves little enough: Let us then up and be doing, and doing to the 
purpose: so by diligence shall we do more with less perplexity. 


22 point (Ho punctuation except period.) J 

RBCBE Fe$n K1SH0 P0RST 
QVWXYR abcde Ighij hlmno pqrst 
uvwxyz 01234 56729 . . 

II time be of all things the most 
precious wasting time must be as w 
Poor Richard says the greatest 
prodigality since as he elsewhere 
tells us lost time is never found 
again and what we call time enough 
always proves little enough Let us 
then up and be doing and doing to 
the purpose so by diligence shall we 
do more with less perplexity. 





Bodooi font, roman, bold, italic , 10 point only. 


ABCDE FCHIJ UMNO PQRST UVTO2 sheds fghij klmao pqrst urwxy* 01234 5*789 
!*' #1X4* ():*-•[] { } m m mm\ I © ' l */?.>, < 

If *i«— bo of ail things tba moat prodeus, wasting tima most ba, aa Poor Zichard cays, tba (mas 
prodigality; tinea, aa ba elsewhere tails as, loot tima is nooar found train; and what am call tamo enough, 
always proves littlt enough: Lot as than up and ba doiac and doing to tba purpose; so by diliganca shall am 
do men with lass parpdesty. 

ABCDE FCSIJ K1MNO PQRST UVTFTT2 aide fghij klmna pqrst aewxye 01334 5*789 

j -~-\i ©• *•✓?,>, < 

If time be a / all thine* **• mxx * t pnecioat, westing time mast be, a s Poor Richard soys, the greatest 
prodigality; since, at he elsewhere tells at, lost time it neeor found. again; end mhos me call time 
enough always preme t little enough: Let at them ap and be doing, and doing to the purpose; so by 
diligence shall me do more with lost perplexity. 

ABCDE PGE2J UMNO PQRST U7TXTZ abode fghij klmno pqrst uwwxys 01234 S5799 * 

!"# IX A *():*-• HH ---\|0*!•/». >t< 

t 

If time bo of all things tba saost precious, wasting tima mast ba, as Poor Zi chard says, tba grteteet 
prodigality; since, as bo olscwhara tails as, loss tima is oarer found again; and what wa call time enough, 
always proves littla enough: 1st as then up sad ba doinc ond doing to tba purpose; so by diligence shall w« 
do mera with lose perplexity. 




Chess, 18 point only 


Note: Our attempt at compatibility -with Stanford iraa only 995 successful. If you use 
a space to indicate an empty white square it will come out narrow due to the 

stupidity of troff. Either include the line 
.es eh 36 


to put yourself in constant spacing mode or else use zero instead of space, 
should also set the vertical spacing to IS points. 
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Clarendon, 14 and 18 point roman only. From SAIL (Paul Martin k Andy 
Moorer) 


ABODE PGHIJ ELMNO PQBST U7WZY abode fghij klmao pqrst 
uvwa cyg 01234 56789 

" #$ < >: -*[]() —-_\I •;♦ /? . > , < 

If time be of all tili ng s tlie most precious, wasting time mast be, 
as Poor Bichard says, tlie greatest prodigality; since, as be 
elsewhere tells os, lost time is never found again; and wbat we 
call time enough, always proves little enough: Let us then up 
and be doing, and doing to the purpose; so by diligence shall we 
do more with less perplexity. 

ABCDE FGHIJ KLMNO PQBST UVWXY abode 
fgkij klmao pqrst uvwxyz 01234 56789 

" #$ i» * ( >: - - [] (j ~ ~ < 

If time be of* all tilings tke most precious, wasting 
time must be, as Poor Bickard says, tke greatest 
prodigality; since, as ke elsewkere tells us, lost 
time is never found again; and wkat we call time 
enougk, always proves little enougk: Let us tken 
up and be doing, and doing to' tke purpose; so by 
diligencejskall we do more witk less perplexity. 
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10 Point Roman 

ASCDE PGSU iO^iNO PQRST TJVWX5TC abed* fghij kiano pqrst urwxyi 01234 
58739 ! ** jl fSk * ( ) * • { J * "• —\ 9 •> ,< ',|IIfit2»T,#in w## A t 9^,'f 1 fl 1 lJ„„ 

IT * t r r « bo of all thisg* tha moat prstdouijWasting tima mast ba,as Poor Ri cha r d says, tha 
outsat prodigality sinco^a ha alsswhara tails us,lost tima is amr found again and 
what wa call time anough,always proraa Uttla anough Lai os than op and ba doing,and 
doing to tha purpot* so by diliganca shall wo do moro with lass parplaaity. 

10 Point Italic 

XBCDE FGH1J KLMNO PQRST UVWXYZ tied* fghij khnno pqnt uvtosya 02331 
5 S 789 !" # p 9 e *(): '-=[] i J ---\w 9 Z, *>i B, T, *, U, 

a, e, a #, a, a, fi, n, s i s 

If time is of *U things the most precious, wasting tims must 4a, as Poor Richard toys, 
the-greatest prodigality; tines, as hs elsewhere tells us, lost time is never found again; 
and what we call time enough, always proves little enough: Let us then up and be 
doing, and doing to the purpose; to by diligence shall we do more with less perplexity. 

10 Point Bold 

ABCDE TGHU XLhCTO Pi^iST CVWIY2 abeda fgfail Umno p<jrst urwxyi 01234 
58739 *1 + / ?• >t < ViZatl *» T* ♦» 

*i “ * hi 9» ii t« »;r 

H H-m. ba of an tM-nya tha most pradous, woting tima must ba, as Poor Richard says, 
tha greatest prodigality? sines, as ha tlsawhero tails us, lost tima is ncrer found again; 
and what wa call tima enough, always proraa llttla enoughs Lot us than up and ba doing, 
and doing to tha purpost; so by dUlgene* shall wa do mora with lass parpladty• 

T?+m Twiw/ 1 V4d t*4 
t Pmat Hffffl M. 3flM . m d Italic 

9 p en ta Rcmaii,3oid,aad I t ali c * 

10 Point Rooan,Bold,and Italic. 

11 Point Roman,Bold,and Italic. 

12 Point Homan,Bold,and Italic. 




Countdown (22 point, upper case letters only.) From SAIL (Paul Martin) 
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Cyrillic, 12 point only 
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Delegate, roman, italic, and bold, 12 point only 

ABCDi FGHIJ UMNO PQ2ST OVWCYZ abcde fghij klaao pqrst uvwxyz 01234 56789 

l "#*** ' ():•-.[] ®t; ♦/?..>, < 

If time te of all tilings tie most precious, wasting time must be, as Poor Richard 
says, the greatest prodigality; since, as be elsewhere tells us, lost time is 
never found again; and what we call time enough, always proves little enough: Let 
us then up and be doing, and doing to the purpose; so by diligence shall we do more 
with less perplexity. 


ABCDt FCSIJ SUMO PQRST UVWXYZ aide fghij llano pqrst umzgz 01234 SS789 

/-#***• r>. - -W; f J ©.♦/?.>,< 

li time be of all things the most precious, nesting time mst be, as Poor Richard sags, 
tAe greatest prodigalitgi since, as he elsemhere tells us, lost time is never found 
again; and what we call time enough, alvags proves little enoughs Let us then up and be 
doing, and doing to t4e purpose; so bg diligence shall we do more with less perplexitg . 







ABOffi raw QKNO KJIST JTOTZ ebcde f*hlj tlmo pqrst urn 71 01534 56709 
I " # 5 * 0 ’ _\ I S t; •/). >, < 

It tile be of ill thlnjs tie Kit precious, nestle* tile mst be, is Poor lichen 
sers, tie fleetest prodljelltn slice, es be elseeiere tells us, lost tlie Is • 
ue«r found s*sli; end »i,t »e cm tile euou*h. el»» 7 , prores little euou*is Let 

"iSp^l 1 ^*- “* “>* “ *»• “ *T queues .bell « do «re 


Fi* find width font, 6, 3, IS, 12, 14 point 
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13 point 


«CCE FWIJ tLPTO POST UYUXY soed* fgftjj Mano pqrst uvuxyz 81234 55783 
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#«s** ()»»-.ti n*--\ !••»♦/?. >,< 


iU' * thTo^oJw t*!LS? . P ~'' ~*t be. >. Poor Riobord 

•ayii. ths grsstast prodigslltm sine*, as ha sl«st*ar« tall, us, lost tins is nsvar- 

“I* t! ** • n0USft ’ Pro^ss littls snougm Lst us than 
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12 point 



ABCOE FGHIJ KLflNO PQRST UVUXY abode fghij Klmno pqrst uvuxyz 01234 
5S783 

!"#$*** ( ) : * - • C 3 

If time be of all things the most precious, wasting time must be. as 
Poor Richard says, the neatest prodigality: since, as he elseuhere 
tells us. lost time is never found again; and uhat ue call time 
enough, a I ways proves little enough: Let us then up and be do i ng. and 
doing to the purpose; so by diligence shall ue do more uith less 
perplexity. ... 


14 point 

AECDE FGHIJ WJTO PQRST UVUXY abode fghi j klmno pqrst 
uvwxyz 01234 9578S 

. < 

If time be of all things the most precious, wasting time 
must be, as Poor Richard says, the greatest prodigality; 
since, as he elsewhere tells us, lost time is never found 
again; and what we call time enough, aluays proves little 
enough: Let-us then up aid be doing, and doing to the 
purpose; so by diligence shall we do more uith less 
perplexity. 



Cachara, re*an, bold, Itall C. 13 point cnly 

The gachaa font is almost indistinguishaole from f U font, 
pointed cut that cup gachan roman and cold fcnts real y * 
eluded anyway for convenience. 


In fact, it has been 
Sigh. They are in- 


terrc PSHIJ KLTfC PQF57 UVUXYZ aocde fghij klmno pqret uvwxyo 31234 S732 

i "fill* () :* - • C ] | {“**—\I ©*:+/?.>,< 

If ties be of all things the eost precious, wasting tiae~aust be, as Poor Richard 
says, the greatest prodigality? since, as he elsewhere tslls us, lost time is never 
found again: and tfiat we cal I time enough, always proves little enoughs Let us then 
up aid be doing, and doing to the purpose? so by di I igenca- shal I ue do more ui th less 

perplexity. 


■ABCDE FGHIJ KLTWO PGXST UUVXTZ atcda fghij klnto pgrst uvwxyr 01234 S67Z9 
i - § s x t'()s * 11 \ 1 --< 

IT tlm ba of a77 things tha aast precious, easting tlm oust bo, as Poor Richard 
says, th* greatest prodigality; sines, as As elsewhere tails us, lost tlm Is navar 
found again; and what we call tlm enough, always proves llttla enough: let us then 
up and ba doing , and doing to the purposa; so by dlllganea shall m do more with lass 
parplaxlty. 


Acrrc fghij JQJTO PGRST UVUXYZ aecda fghij kiano perst uvwxyz 31234 S57SS 
!"#***’ (J * a - • C 1 f J --—\ | •* « +/?.>,< 

If tiae be of all things the aoet pre c ious, wasting tiae oust be, as Poor Richard 
says, the y aat e a t prodigality; since, as ha elsewhere tells us, lost ties Is never 
found again; OTd diet ue cal I tiae enough, always prove s little enough: Let us then 
iS> and ba doing, and doing to the pu rpos e ; so by diligence shall ue do acre with less 
perplexity. 

Greek, 10 point only 

Tiia font provides an alternative to the Greek characters on the standard special 
foah 

ABCDZ FGEU XUOfO PGRST UTWXTZ abode fyhij khnno pqrat trorsy 

ibxaz grsi# kamno nsPTT. Ttistz *rw Am* *****. »*•#? 

U nm b* *4 «U rm-r* ryt xn TW* s-swr r\\m tv** it er Hm 0 n* Tftmm* 

er v* niXr n Wr «*• w xn# *ym» mi .xr ■* Z«U nw «**Wt 

■> *j* fiew JwrrXs «»WTf 1 m> ** rx* v* mi it lamy mi lamy m n» rm«« n £* lUrprt* «V«U 
M U x« •«! Wr T***Um*+ 






The hlS font Includes a subset of the hl3* • graphic character eet, plus a 
feu logical extensions to allou forms and diagrams to be drawn. The characters 
r« the same as the hlS's graphic interprataticn set. 

* a b c d a f a t u v a n h i R I 

I - + i J 1 ttH - 1 + 

The characters are daaigned to overlap. 


Example of ueage for diagrams: 



















Hebrew, 16, 24. and 38 point onlj 


16 point 

icrr 5iT3 rrcil sp^rs nrrr? *n sSsj 2 tr wr os* 56*®? 

«" # n x. () *. - u n ~ ~ \ i @ •'« r ?. > . < 

eny srninTi JTss Tff h: yrryrry^ snlrr? Stt ar^n a-yrrc^tr 
«r»n:«s7 'a =FT= n*r^rc STpsraeky. t*fr «ir $njr ! n **n 
*1 53 3“ 3*55. 


nw? tny 
: tfr yr^j 


24 paint 

sec* :n y ibis: sp-ica . mm • e 


&-»s . 


en ons*! n n o x: no bb a on c i ri n 
2 i * ce vs. a row an jrwxjw a r *6e ca 
n msw 1 ? . 


38 point (rather ragged) 

n j? jxs 2pTsa irm 








10 point Hershey 


ABODE FGHU KL2£N0 PQRST UVTTXYZ abode fghij kirn no pqrst uvwxyz 01234 567S9 !, 3, 

S. k, \ (.).•. [. ]. \. 

\(em - ^ \(btt - *, \(sq - •. Mru - - \(14 - K. \(12 - & \(24 - %. \(Ii - 

fl. MU - fl. \(« - fl. \(n - a. \(n - flL-Mde - \ \(dg - t. M*m - \ Met - «Mrg - • 
Moo «• • . 

Then you flex your fingers in a coffin. It can baffle a giraffe. 

ABODE FGHIJ KLSNO PQRST UVWXYZ abode fghij kimna pqrst umusyz 01234 5678S /. 

S. X *, •. (,).*. . 

Mem Mba - •. Msq - •. \(ru - - Ml4 - %\(1Z - J$\(34 - 2Mfi - fi. 

Mfl -*Mfl - ff. \(T1 «* ffl, \(F1 -* ffl. Mde -* Mdg - t. \(lm - \ \(ct - «\(rg - *\(co 

„ • 

When you ffex your fingers in a coffin, it eon baffle a giraffe. 

ABODE FGHU XL3TNO PQRST UYTXTZ abode fghij IcLmno pqrst u tw xyx 01234 56789 !. S. 
X k, *,(,). i» *» •# [■ ]■ >St /« 7« • 

M«m \(bu \(aq - •. \(ru - _ Ml4 - KM 12 - Jg\(34 - J\(fi - fl. 

\(fl - fl. \(fl - fl. \(Fl «• 111. MFl *• BL Mde - Mdg -• t. Vim - *. \(ct -• ?Mrg - P\(eo 

Then you flex your fingers in a coffin. It can baffle a giraffe. 

From special font: = 

Special characters: Mpl *• +. Mmi *» —. M®q — *. M** ”• •. \(sc - }, \(aa «♦ *, Mg* *• *. 
Mul - — Msl - /. M*& - «. M*b - fi, M*g - 7. \(*d - i. M*« - t. M*z - C. \(*y - q. 
\(*h - d. M*l - t. M*fc «• *. Ml ■* M*m - p. M*a - v, M*e - (. \( m o - o. M*p - 
\(*r - p. M*» - o, \(ts - ?. \(n - r. \(*u - v, M*i - p. M*x -* x. \(*q - M*» - «• 

M*A - A. M’B - B, M*G - r. M*D - A. M*E -E. M*2 - Z. M*Y - H. \(*H - 0. \(-I - I. 
M*K - K. M*L - A. M*H - H. M’N -* N. M*C - 2. M*o - 0. M’P - n. M*R - P. NCS - r. 
M*r - T. M*U - T. M*F - *. M*x - X. M*Q - *. M*» - a Msr - V. Mrn - “. M>= - i, 

\(<= -» as, \(== - *, M~s ** Map •* •*. \(! s ** M*> *• ■*. \(<* - •». Mua - t. Mda - 

*, \(mu «• x, M^i <* 4, \(+- -• i, Mcu *• u, \(ca - ft. Msb -* c, Msp "* 3. \(ib - C. \(ip - 
2. Mli - Mpd - a. Mgr *• v, Mao - Mi* •* /. Mpt - «. M«q ** *. \(ao - -. \(br - L 
Mdd - t. Mrh - rMlh *• \(^a **0 \(or - |. Mei - O. Mlt -* i Mlb -1 Mrt - f. Mrb - J. 

\(Uc - \(rk -}. M^ T -1. Mli -* l \(rt - J. \(lc -1. Mrc - ] • 

If time be of all things the most precious, wasting time must be. as Poor Richard says, 
the greatest prodigality: since, as he elsewhere tells us. lost time is never found again: 
and what we call time enough, always proves little enough Let us then up and be doing. 
And doing to the purpose: so by diligence shall we do more with less perplemty. 


This Is an example of a sample In various fonts. 






Hershey font. This la the default font for vtrofL Roman. Italic »n d EH ii in. fl 7 a q i n 
U. 12. 14. 16. 18. 20. 22. 24. 28. eud 36 point. The touting .xJ?pl.7S. 10 poiL. 10 ' 

If Uae be of all things the moat precloua. treating time muat be. aa Poor Rich«rJ 
the g^ateat prodigality: since, aa he elaewhe^Tella «a “o“t tto.“ n.^r fo^iS 
and what we call ta. enough always proves little enough: Let us then up andbe^S 
and doing to the purpose; so by diligence shall we do more with less perplexity. 

****' thagrealast prodigality: «nct. or ha tlsawhert tails us. lost ttm* 
« rurv*T found ogczn; <md what wa call tima rrwugh, always proves littla ancIcA-lIF 

*** W»*- « *v ciiiip^tc. sheU u,. do mere 


If time be of all things the moat precious, wasting time muat be aa Poor RJe*.»rrf « n 
th. greatest predlgslity; stnc. «hT.b.rt “ 7 * 

?**j“ and. shot n ceil time enough, ebreys pro.es Uttle enough; Let us thenm end 

t. domg ^ domg to the purpose: so by diligence shell e, domore eith““ 
perpiftscj. 


9 point Romma. H4 «ztd 

9 point Sflp an, Bold, Italic* 

10 point Roman. Bold and Italic. 

11 point Roman. Bold, and Italic. 

12 point Roman, Bold, and Italic. 


14 point Roman, Bold, and Italic. 

16 point Roman, Bold, and Italic. 

18 point Roman, Bold, and Italic. 

20 point Roman, Bold, and Italic. 

22 point Roman, Bold, and Italic. 

24 point Roman, Bold, and Italic. 
28 point Roman, Bold, and 
Italic. 


36 point Roman, Bold, 
and Italic . 





Meteor, roman, bold, italic, 8, 10, 12 point, no 12 point Italic. 


ABCDE FGHU ELMNO PQBST UVWXFZ abode fghij fclmno pqrst uvw-ryz 01234 56789 

s - #$ %&'()!»-■[] (I---M • ’*•♦/?.>. < 

If time be of all things the most precious, wasting time must be, as Poor Bichard ays, the 
greatest prodigality; since, as he elsewhere tells us, lost time Is never found again; and 
what we call time enough, always proves little enough: Let us then up and be during and 
drriTig to the purpose; so by shall we do more with less perplesdty. 

^ prpr pQElJ rrjvrvo pqrst UTWZTZ abode fghij him no ptjrst u vwxyz 01234 S6789 

J I j < 

If ti-m* fot all things the most precious, wasting time most be, as Poor Richard says, 

the great est prodigality, since , as he elsewhere tells us, lost time is never found 

# 

ag ai m and what we call time enough, always proves little enoughs Let us then up and 
be doing, and doing to the purpose; so by diligence shall we do more with less 
perplexity. 

Aurrre FGHU XLM&0 PQRST XJVWZ7Z abode fghij Ttitn-no pqrst uvwxyu 01234 
56789 

\ 

! - # 8 % fc • ( ) : ■ - • C ] H -I e • I «• / ? . > . < 

If r»T be of all things the most precious, wasting time must be, as Poor Blehard 
says, the greatest prodigality; since, as he elsewhere tells us, lost time is never 
found again; »n«i what we time enough, always proves little enough: Let us 
then up and be doing, and doing to the purpose; so by diligence Shall we do more 
with less perplexity. 






Microtraxnms font, 10 point only 


ABCOS FGHU KLMNO PCRST UVWXY adeda ffittj Umno pqmt uvw*yx 01234 5B7B3 

i« #s*«s*Ui«-••[] H M •' *♦/>• < 

. 

If tima ba cf oil things this meat praricus, anting tims must ba, as Pcty Richard says, ths 
TeatBSt prcdgaiity, arcs, as ha aisawhara tails us, lest tims Is navar found again; and what 
ws call tims ancugh, always pnwas Bttia ancugh: Lat us than M3 and da being, and being to 
p jr pr- * — L so by dJTcanca shall wi bo mcra with lass parpi®aty. 


3R3ona font. 24 point onlg 


ABC353E 51M0 £&£;5C HUHfXgS 

abebe fghij hlmno pqrst oooixgz 0123-4 56789 

l" # $ * s * n : - H ~ ~ ® S ?. 

> . < 

Philadelphia is the most pecfcsniffian of American 
cities. and thos probablg leads the mo rid. 

- 3j. 3L Kenchen 






Nonie, remen, bold, Italic , S, 10, 12 point 


• point 

JtaCSE ?<3rtJ KLMNO FOUST UVWXYZ itcd* fjMJ kfimo pqrst uvwsyt 01Z34 367*8 

II I—-M ••!*/».».< 

tf ttiw to of ail thmg# tfto moot prociouo, wtttng ttno mu at bo, u Foot Reft art aaya, tho proatoat prodlgamyi 
tinct, aa ho otaovuhofo toila ua, loat ttno la nooor found again; and what om can ttno onougft, aiwmyi orovoa iirtio 
•nought Lot ua tfton up and do doing, and dotig to tfto purpoao; ao by dfllgonco aftail wo do moro with loaa 
porp laxity. 


ASCO£ FQHU KIM NO PQAST UVWXYZ meOo tghij klmno pqrtt uvwxyz 01234. 56740 

tf ttmo 4m of a// trtngz mo moat proof out, wanting ttmo must do, av ^oor AtcnarO lays, too groanat proof gat fry j a/neo, 
aa no ouw/ort hw/i ua, /oar tfmo /a nooor found againy and w/iar wo ea// tfmt onougrt, anoayt prows nttto mnougru 
Lot ua man up and do doing, and do/ng to mo purpoaof ao Py d///gonco ana// too do moro «r/m /oaa porprojr/ry. 


A6C3C FQHU WJVWO FQXST UVWXYZ aPedo fgftij HPnno pgrat uvwxyz 01234 50718 

()»•-• t3.l I "—xl •• «♦/*.>•< 

tf ttmo do of ail things 8a moat prooioua, waatjng timo must to, aa Poor Rleftard aaya, tfto groats at prodigality; 
anea, as ho tlsuwliuru tails ua, loot tdno la novor found again; and what wo call ttno onougft. Always prove* 
tttam on ought Lot ua thon up and bo doing, and doing to *io pispoao; ao by dlOgoneo shall wo do moro wrtn loaa 
porp laxity. 


10 point 

ABC0E FGHIJ KLMNO PQRST UVWXYZ abode fghij kirano pqrst uvwxyz 01234 56789 

; 

If time be of ail things the most precious, wasting time must be, as Poor Richard says, the 
greatest prodigality; since, as he elsewhere tells us, lost time is never found again; and 
what we call time enough, always proves little enough: Let us then up and be doing, and 
doing to the purpose; so by diligence shall we do more with less perplexity. 

ABCD£ FGHIJ KLMNO PQRST UVWXYZ abode fghij Klmno pqrst uvwxyz 07234 56789 
r §SZf( ):-••[ ' + /?.'>.< 

If time be of all things tho most precious, wasting timo must be, as Poor Richard says, the 
greatest prodigality; since, as.he elsewhere tells us, lost time is never found again; and whet 
we call time enough, always proves little enought Let us then up and be doing, and doing to 
the purpose; so by diligence shell we do more with less perplexity. 


ABCOE FGHIJ KLMNO PGR ST UVWXYZ abede fghij Jdmno pqrst uvwxyz 01234 56739 

!-#•%*•(>.■-■[31 

tf time be of ail things the most precious, wasting time must be, as Poor Richard says, 
the greatest prodigality; since, as he elsewhere tells us, lost time is never found again; 
and wh*t we call time enough, always proves little enough: Let us than up end be doing, 
and doing to the purpose; so by diligence shall we do more with less perplexity. 


12 point 

ABODE FGHIJ KLMNO PQRST UVWXYZ abode fghij klmno pqrst uvwxyz 01 234 
56789 

1 " \ 1 ®'?♦/?•>»< 

If time be of ail things the most precious, wasting time must be, as Poor 
Richard says, the greatest prodigality? since, as he elsewhere tells us, lost 
time Is never found again? and what we call time enough, always proves little 
enoughs Let us then up and be doing, and doing to the purpose; so by 
diligence shall we do more with less perplexity. 

ABODE FGHIJ KLMNO PQRST UVWXYZ abode fghij klmno pqrzt uvwxyz 01234 
5678 9 

i * §$%* § c )** •• cm ***— 

If time be of a// things the most precious , westing time must be, as Poor 
Richard says, the greatest prodlgaiityt since., as he eisewhere tails us , lost 
time Is never found eg aim end what we call time enough , always proves little 
enoughs Let us then up and be doing , and doing to the purpose ? so by 
diligence shall we do more with less perplexity* 

ABODE FGHIJ KLJVWO PQRST UVWXYZ abode fghij kimno pqrst uvwxyz 
01234 56739 

If time be of all things the most precious, wasting time must be, as Poor 
Richard says, the greatest prodigality? since, as he elsewhere tells us, 
lost time is naver found again; and what we call time enough, always 
proves little enough: Let us then up and be doing, and doing to the 
purpose? so by diligence shall we do more with less perplexity. 




<£>13 English, S, 14, an3 IS point only. (This font is calle3 
"oIHenglish" on line.) 

IfM* 

( P®C2S $5113 515^3© ljJ(5§E$<2 £S JS2i| «l»~to Egtjij Uoa. pqnt iiHmp (TI7 54 339 
■ # * :• 11---\ •*: •>•< 

£ ton to«f dUfrtaai Hr* ant pncte*. todttrg ton and to. as^ar Stoud am.lto ytatoatptortalfann. t* to 
ttobns* >«fl« ml laid tot* to attor £gnd naiad boat to ail ton enur. altocs *cuto » Idto i m i jrT^ i f a* Hu os ad to 
tong, 'ad tong b Hr, popnCsi kj totgoto «to& to to an to* to. p^toto'* 


%4 paint 

«L3?aP92£ ^(53^13 3jHpp2?<& TPH^CT *1*3* tghia kton. 

pqrst awxQZ 03234 66789 

" # s ( J ~~_\ © : . > * < 

U tixrxto b* o2 ad thing* th* mast precious. wasting txm* mast b*. as 3?oar 
^Jirhar-3 says, th* greatest predlgalityjsxnc*. as h* tkwtort tails as. last 
thn* is n t ^r {mind agaui^md what v* call ton* enough, always pr o ves 
*noagh;3£*t as than op and la* doing, and doing ts th* puryum^o by 
SHigenc* shall ar* da mar* with less perplexity. 


IS point 

g.33<533? ^<5^23 3“©?ST 2PTWXYZ 

abc3e fghif klxnno pfjrst uvivxya 01234 oOTS9 

"# • <) - M - ~\ * • > • < 

If time he of all things the most precious, wasting time 
must be, as 3?oor l^icharS says, the greatest pro3igaHty 
since, as he elsewhere tells us, lost time is nm foun£ 
again an3 what we call time enough, always proves little 
enough an3 1 think I« wasting time typing all this stuff 






PIP FUMT, m POINT DHL¥, HO LDWEH CASE 


AECDE FCHIJ KLMH13 PQRST UUWHYZ DTEZS4 55733 

• " # - H-@ 4 ; ?. > t < 

IT CHULA PROBAELV BE SHOWN BY FACTS BHD FIGURES. THAT THERE IS MU 
DISTINCTLY HAT1UE AMERICAN CRIMINAL CLASS EXCEPT CUN CRESS. 

- MARX TWAIN 

Riltifl fat* U fUtt alt 

I2Q2 TSHU EXE RET ITOT2 this f<Ul Mmu »nt mxn RS 

^ ® :♦/!*>.< 

ff tlu h rf til tilafs tta ist palas. itstiif tlu ust it. u ter Uttar! an* tta (mttrt irtljiiUr taut, a ta 
tlnvtan tills tx. ta tlu is uar fata tfiic tta *tat •• nil Uu itayi. tlwyj jnax Uttii no)k Ut a ttai ty tta it 
( BH , tta iiiit u tta ftryai; a iy UUfius ttail n it m till Its Jtryiixitr. 

*. 

Script, 18 point only. This font appears to be almost identical, to the 
“Coronet” font from SATT., except that the period and one other glyph 
of Coronet are missing a row, and Coronet is supposed to be 16 point. 

(They are both really the same size.) 

JBC^C 3QJ13} JCJ1WVO PQZSD VVWXt/Z .U, 

ffLij Limas amwiys Of234 36789 

" # .• \ l - ~ —\ O , . > . < 

3f Urne Le •/ mil tLinys iLe mmsl pee clems, maslimy lime mmsl Le, ms P eme 
$ icLatJ says, tLe yrratssi preSiy silly; since, ms Le tlsewneee tells ms, last time is 
meeee fern*. S my minx mnJ m Lai me call lime enemy n, always femmes hid* enemy L; all ft 
as iLet « *f mnJ Le Jsiny, mnS Jsiny tm the f me feme; im Ly Silly ence *~all me Je 
more witL less fee fleetly* 





sgeeee, fece? arttr, ee ceeee eesg 


fffaaiw 7 ECCJ (R Myrm PECS'S? EVC5SV2 ISSSIX S^SS 
V ” § ' * 6 S j j “ ~ —\ • >» < 


5UB (r-CSEEK FEEt CS EE ESIEGEGES EEECEE FEE 
PEEFEEEE FEEECE'FCEES. VS EES SEE EEVEEfEEG IDF 
poms EECCEStf EEESEESEGG, 


«« g E G E E C5 <*> 


SIGN, 22 POINT ONLY 


ABODE FGHIJ KLMNO PQRST 
UVWXYZ >« 01234 56789 

! " # ’**-*• H ~ ~ — @ ;/.>,< 

THIS FONT WAS INVENTED BY A 
DRAFTSMAN WHO HAD LOST HIS 
FRENCH CURVE. » SO IT GOES € 

LOWER CASE L IS », LOWER CASE 
R IS <. 







Sb« hsshey foes. This font b identical to too heifer font exospt that the point an « «» pcirt 
^Jf^toWTtobles are the* t«d for to. real cyp«.aar. Hearn. this font a ntal w«n 
that are to be seat to *typesetter toakianth. spacing nd so on a 

^^Lr^R^maa. ita* aad Boldin 8. 8. 10. 11. 12. H. «d 16 point. The following taaplos 

n 10 point. 

ASCD E FGHU KLH NO PORST tmr^TI abed. fgtf kfaao pc^at mnney* 01234 5678S 

! -#SX Jt* ( ) : CIH ~ ~ —M ® “•** /? • c 

U to. be of all tha most predous. westing tee moat be. as Poor Richard says. ±a greatest 

Predirtiity; dues, as ha adhere toils u. lost tae is n«- found a«am: and what we oil dm. 
ttccih. dwsys proves little enough: let us than up aad be doing, and doing to tha purpose so by 
do mora ▼itii its perpltaatp. 


ASCDE FGSIJ KL2IHO PQRST WW XYZ obedm ffivj kbwo jrp^t rac&a 01234 £6789 
!" §SX *•():••* /?.>.< 

/fbT. be Of on brings*. rwrfprecww «=<ing dm. wso* 6c as Poor Rich** jr«*st pwajoidar 

Mb w and Wuri*. cad dm. mn**. 

pipMsbj. 


ABC13E rau SLS NO PQRST 0 V T1T2 abode fghil klamn pvat arezyz 03234 *789 

/?.>.< 

U dra. b. <rf an thin«s th. mat pnaoos. ▼asdn* da. most ^ b Po» Sic^ ays. toe ^tost 

-_ nbT - M riM.ha tails ta. leal dm. is nerer foond again; and -.hat we «U dm. 

mao^i^alwajs prwres little enough: Let us thm up and be dein* and doing to the purpose so by 
ahmQ do lau rt *ith. 1st perploMy. 


Ipiiatooa. M tatU*Mo. 

9 point Homan, Boid and Itntir . 

10 point Roman, Bold, and liaise, 

11 point Roman. Bold and ItsSs* 

12 point Roman. Bold and Ibis. 

14 point R oman, B old and IiaJas. 

16 .point Roman, Bold, and /iaiic. ■ 








Tines font*, ronan, «nd bold. 10 point only. ... 

Ti-o font* thowad up in a directory labelled "timearotnan-alon* with threeother fontt which t«M oat 
to ho nonie, meteor, and now. fothie. They an probably not really time* font*, but wen to be pretty dot 
Notice the top of the "2" for a dear difference from a real Tinea Homan font. 


It i. oar dasire to haee a real, difitiied eemoa of the tinea fontt from the phototypeaatter. Vo eeentaally 
niu to do this. At that point, the tines font will probably replace the berthey font aa the default Such a 
5La font is already arailabl* from John. Hopkins Dnirenity for a fee, but we couHn t rediambut. it «o 
wm plan do difitixt thorn ranolooo. 


AHCDE FGHU m£NO PQEST UWXTZ abode f*hii klnno pqm uewxy* 01234 56789 

! - # I©';*/?•>.< 

\ ^ n,, h, H, h, fi, fl, fi, ffi, ffl» *» t, ’»Pf* 

ABC2E FCEIJ KL21NO PQRST UVWZTZ abode //«/ Unuto pqru newxyz 01234 36739 

J * ** —\ I O' :*/?•> • < 

•, o, fl, , k, H, A A #• JR *• t» 

jjtrpv TT.TTTT TT.VT Jn PQBST W®TXZ abode ffhij Uw tvtt uewzys 01234 56789 














* 






F0NTNAHES(7) 1IUNIX 2.0 (QU68000) F0NTNAMES(7) 

NAME 

font names — table of font names in short and long formats 
SYNOPSIS 

cat /usr/lib/fontinfo/kurz 
DESCRIPTION 

For the usage of fonts other than the default ones in trojf (or Itroff or 
vtroff resp.) the names of these fonts must be specified twice. The full 
name (see below) is used to control the phototypesetter or the postpro¬ 
cessor ( Icat or vcat ). Troff itself needs the specification of the font 
name in a short form for the selection of the corresponding font size 
tables in a .fp -command. 


long name 

short name 

long name 

short name 

apl 

ap 

hl9 

hn 

basker.b 

bb 

he brew 

hb 

basker.i 

bi 

meteor .b 

mb 

basker.r 

br 

meteor.i 

mi 

bocklin 

bk 

meteor.r 

mr 

bodoni.b 

ob 

mona 

mn 

bodoni.i 

oi 

nonie.b 

nb 

bodoni.r 

or 

nonie.i 

ni 

chess 

ch 

nonie.r 

nr 

clarendon 

cl 

oldenglish 

oe 

cm.b 

cb 

pip 

PP 

cm.i 

ci 

playbill 

pb 

cm.r 

cr 

script 

sc 

countdown 

CO 

shadow 

sh 

cyrillic 

cy 

sign 

sg 

delegate.b 

db 

stare.b 

sb 

delegate.i 

di 

stare.i 

si 

delegate.r 

dr 

stare.r 

sr 

fix 

fx 

times.b 

tb 

gacham.b 

g*> 

times.i 

ti 

gacham.i 

gi 

times.r 

tr 

gacham.r 

gr 

times.s 

ts 

graphics 

gf 

ugramma 

m 

greek 

gk 




FILES 

/usr/lib/fontinfo/kurz 
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FONTS(7) 


NAUE 

font list — table of available 
DESCRIPTION 


font 

available 

sizes 

R 

6 

7. 

8 


20 

22 

24 

B 

6 

7 

8 


20 

22 

24 

1 

6 

7 

8 


20 

22 

24 

S 

6 

7 

8 


20 

22 

24 

apl 

10 



basker.r 

12 



basker.b 

12 



basker.i 

12 



bocklin 

14 

28 


bodoni.r 

10 



bodoni.b 

10 



bodoni.i 

10 



chess 

18 



clarendon 

14 

18 


cm.r 

6 

7 

8 

cm.b 

6 

7 

8 

cm.i 

6 

7 

8 

countdown 

22 



cyrillic 

12 



delegates 

12 



delegate.b 

12 



delegated 

12 



fix 

6 

9 

10 

gacham.r 

10 



gacham.b 

10 



gacham.i 

10 



graphics 

14 



greek 

10 



hl9 

10 



hebrew 

16 

17 

24 

meteor.r 

8 

10 

12 

meteor.b 

8 

10 

12 

meteor.i 

8 

10 


mona 

24 



nonie.r 

8 

10 

12 

nonie.b 

8 

10 

12 

nonie.i 

8 

10 

12 


and point sizes 


10 

36 

11 

12 

14 

16 

18 

10 

36 

11 

12 

14 

16 

18 

10 

36 

11 

12 

14 

16 

18 

10 

36 

11 

12 

14 

16 

18 


10 

11 

12 

10 

11 

12 

10 

11 

12 


fonts 

9 

28 

9 

28 

9 

28 

9 

28 

9 

9 

9 

12 

36 
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oldenglish 

pip 

playbill 

script 

shadow 

sign 

stare.r 

stare.b 

stare.i 

times.r 
times.b 
times.i 
times.s 

ugramma 


» * 


8 14 18 

16 
10 


18 

16 

22 


8 

9 

10 

11 

12 

14 

16 

8 

9 

10 

11 

12 

14 

16 

8 

9 

10 

11 

12 

14 

16 


10 

10 

10 

10 
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Screen Updating and 
Cursor Movement Optimization: 

A Library Package 


This document describes a package of C library functions which allow the user 
to: 

• update a screen with reasonable optimization, 

• get input from the terminal in a screen-oriented fashion, and 

• independent from the above, move the cursor optimally from one point to 
another. 

These routines all use the /etc/terrneap database to describe the capabilities 
of the terminal. 
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1. Overview 

In making available the generalized terminal descriptions in /etc/termcap, much informa¬ 
tion was made available to the programmer, but little work was taken out of one’s hands. The 
purpose of this package is to allow the C programmer to do the most common type of terminal 
dependent functions, those of movement optimization and optimal screen updating, without do¬ 
ing any of the dirty work, and (hopefully) with nearly as much ease as is ne c essa r y to simply 
print or read things. 

The package is split into three parts: (1) Screen updating: (2) Screen updating with user 
input; and (3) Cursor motion optimization. 

It is possible to use the motion optimization without using either of the other two. and 
screen updating and input can be done without any programmer knowledge of the motion op¬ 
timization, or indeed the database itself. 

1.1. Terminology (or. Words You Can Say to Sound Brilliant) 

In this document, the following terminology is kept to with reasonable insistency: 

window. An internal representation containing an image of what a section of the terminal screen 
ma y look like at some point in time. This subsection can either encompass the entire ter¬ 
minal screen, or any smaller portion down to a single character within that screen. 

terminal Sometimes called terminal s cree n. The package’s idea of what the terminal’s screen 
currently looks like, Le., what the user sees now. This is a special screen: 

s aves c This is a subset of windows which are as large as the terminal screen, i.e., they Stan at 
the upper left hand comer and encompass the lower right hand comer. One of these, 
miser, is automatically provided for the programmer. 

1.2. Compiling Things 

In order to use the library, it is necessary to have certain types and variables denned. 
Therefore, the programmer must have a line: 

#indude < curses.h> * 

at the top of the program source. The header file <curses.h> needs to include <sgtty.h>, 
so the one should not do so oneself 1 . Also, compilations should have the following form: 

cc l /lags ] file -. —1 curses — liermlib 
1-3. Screen Updating 

' In order to update the screen optimally, it is n ec e ss a r y for the routines to know what the 
screen currently looks like and what the programmer wants it to look like next. For this pur¬ 
pose, a data type (structure) named WINDOW is defined which describes a window image to 
the routines, including its starting position on the screen (the (y, x) co-ordinates of the upper 
left hand comer) and its size. One of these (called curscr for current screen) is a screen image 
of what the terminal currently looks like. Another screen (called stdscr, for standard screen) is 
provided by default to make changes on. 

A window is a purely internal re pre s entation. It is used to build and store a potential im¬ 
age of a portion of the terminal. It doesn’t bear any necessary relation to what is really on the 
terminal screen. It is more like an array of characters on which to make changes. 

When one has a window which describes what some part the terminal should look like, 
the routine re/rvshO (or wrefreshO if the window is not stdscr) is called. refreshO makes the ter- 


1 The s c re en pactaie also uses the Standard I/O library« 
(but harmless) for the pr©trimmer to do iu too. 


so <cancs«h> indudes <stdio.ii>. It is redundant 
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minal in the area covered by the window, look like that window. Note, therefore, that chang- 
something on a window does not change the terminal. Actual updates to the terminal screen 
vl made only by cailing refreshO or wrtjreshO. This allows the programmer to-maintain 
several different ideas of what a portion of the terminal screen should look like. Also, c ^ n 8« 
can be made to windows in any order, without regard to motion efficiency. Then, at will, the 
programmer can effectively say “make it look like this,” and let the package worry about the 

best way to do this. 

1.4. Naming Conventions 

As hinted above, the routines can use several windows, but two are automatically given: 
cursor which knows what the terminal looks like, and stdscr, which is what the programmer 
SSS the terminal to look like next. The user should never really access curscr dtrectly. 
Changes should be made to the appropriate screen, and then the routine rrftesnO (or 
wrejreshO ) should be called. 

Many functions are set up to deal with stdscr as a default screen. For example, to add a 
character lo stdscr, one calls addchO with the desired character. If a different window ,s to be 
used the routine waddchO (for window-specific addchO) is provided-. This convenuon oi 
prepending function names with a “w” when they are to be applied to specific windows is con- 
Stent! Tbs only routines which do not do this are those to which a window must always be 

specified. 

In order to move the current (y, x) co-ordinates from one point to another, the routines 
moveO and wmoveO are provided. However, it is often desirable to first move and then per¬ 
form some I/O operation. In order to avoid dumsyness, most I/O routines can be preceded by 
ih™ tSfc “dt" md the desired (y, x) co-ordinates then can be added to the arguments to the 

function. For example, the calls 


move(y, x); 
addch(ch); 

an be replaced by 

mvaddch(y, x, ch); 
and 

wmove(win, y, x); 
waddchfwin, ch); 


can be replaced by 


mvwaddch(win, y, x, ch); 

Note that the window description pointer (win) comes before the added (y, x) co-ordinates, 
such pointers are need, they are always the first parameters passed. 


If 


2. Variables 

Many variables which are used to describe the terminal environment are available to the 
programmer. They are: 


type _ name 

WINDOW • curse: 

WINDOW • stdscr 

char ’ Def.term 


description _____ 

current version oi the screen (terminal screen). 

standard screen. Most updates are usually done here. 
iji»fauit terminal type if type cannot be determined 


5 Actually. addchO a really a “#denne" macro with arguments, as are most of the Tuncuons' which deal with 
miser is a deiaulL 
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bool 

My_teim 

use the terminal specification in Def^term as terminal, 
irrelevant of real terminal type 

char * 

ttytype 

full name of the current terminal. 

int 

LINES 

number of lines on the terminal 

int 

COLS 

number of columns on the terminal 

int 

ERR 

error flag returned by routines on a fail. 

int 

OK 

error flag returned by routines when things go right 

There 

are also several “#define 

'* constants and types which are of general usefulness: 

reg 

storage class “register” (e.g.. reg int /;) 

bool 

boolean type, actually a “ 

char" (e.g.* bool doneit:) 

TRUE 

boolean “true’* flag (1). 


FALSE 

boolean “false” flag (0). 


3. Usage 




This is a description of how to actually use the screen package. In it, we assume all up¬ 
dating, reading, etc is applied to adscr. All instructions will work on any window, with chang¬ 
ing the function name and parameters as mentioned above. 


3.1. Starting up 

In order to use the screen package, the routines must know about terminal characteristics, 
and the space for cursor and adscr must be allocated. These functions are performed by in- 
itscrO. Since it must allocate space for the windows, it can overflow core when attempting to do 
so. On this rather rare occasion, iniacrO returns ERR. initscrO must atways be called before 
any of the routines which affect windows are used. If it is not, the program will core dump as 
soon as either atner or adscr are referenced. However, it is usually best to wait to call it until 
after you are sure you will need it, like after checking for startup errors. .Terminal status 
changing routines like nlO and crmodeO should be called after iniacrO . 

Now that the screen windows have been allocated, you can set them up for the run. If 
you want to, say, allow the window to scroll, use scnllokO. If you want the cursor to be left 
after the last c han ge , use ItavcokO. If this isn’t done, rtfrtshO will move the cursor to the 
window’s current (y, x) co-ordinates after updating it. New windows of your own can be creat¬ 
ed, too, by using the functions ntyrwinO and sufr»m0. deMnO will allow you to get rid of old 
windows. If you wish to change the official size of the terminal by hand, just set the variables 
LINES and COLS to be what you want, and then call iniacrO. This is best done before, but can 
be done either before or after, the first call to iniacrO , as it will always delete any existing adscr 
and/or cursor before creating new ones. 

3.2. The Nitty-Gritty 
3.2.1. Output 

Now that we have set things up, we will want to actually update the terminal. The basic 
functions used to change what will go on a window are addchO and moveO. addchO adds a 
character at the cunent (y, x) co-ordinates, returning ERR if it would cause the window to ille¬ 
gally scroll, i.e., printing a character in the lower right-hand comer of a terminal which au¬ 
tomatically scrolls if scrolling is not allowed. moveO changes the current (y, x) co-ordinates to 
whatever you want them to be. It returns ERR if you try to move off the window when scrol¬ 
ling is not allowed. As mentioned above, you can combine the two into mvaddchO to do both 
things in one fell swoop. 

The other output functions, such as addstrO and pnnrwO, ail call addchO to add characters 
to the window. 

After you have put on the window what you want there, when you want the portion of 
the terminal covered by the window to be made to look like it, you must call rejreshO. In order 
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to optimize finding changes. refreshO assumes that any pan of the window not changed since 
the last refreshO of that window has not been changed on the terminal, i.e., that you have not 
refreshed a portion of the terminal with an overlapping window. If this is not the case, the rou¬ 
tine louch'MinO is provided to make it look like the entire window has been changed, thus mak¬ 
ing refresh0 check the whole subsection of the terminal for changes. 

If you call wrejreshO with curscr , it will make the screen look like curscr thinks it looks 
like. This is useful for implementing a command which would redraw the screen in case it get 
messed up. 

3.2.2. Input 

Input is essentially a mirror image of output. The complementary function to addchO is 
getchO which, if echo is set, will call addchO to echo the character. Since the screen package 
needs to know what is on the terminal at all times, if characters are to be echoed, the tty must 
be in raw or cbreak mode. If it is not, getchO sets it to be cbreak. and then reads in the charac¬ 
ter. 

3.2.3. Miscellaneous 

All sorts of fun functions exists for maintaining and changing information about the win¬ 
dows. For the most pan, the descriptions in section 5.4. should suffice. 

3J. Finishing up 

l in order to do certain optimizations, and, on some terminals, to work at ail. some things 
must be done before the screen routines Stan up. These functions are performed in gemmodeO 
and senermO , which are called by initscrO. In order to dean up after the routines, the routine 
endwinO is provided. It restores tty modes to what they were when initscrO was first called. 
Thus, anytime after the call to initscr, endwinO should be called before exiting. 

4. Cursor Motion Optimization: Standing Alone 

It is possible to use the cursor optimization functions of this screen package without the 
overhead and additional size of the screen updating functions. The screen updating functions 
are designed for uses where parts of the screen are changed, but the overall image remains the 
same. This indudes such programs as eye and ri * * 3 * . Certain other programs will find it difficult 
to use these functions in this manner without considerable unnec e ssary program overhead. For 
such applications, such as some “err hacks"* and optimizing cat(l)-type programs, all that is 
needed is the motion optimizations. This, therefore, is a description of what some of what goes 
on at the lower levels of this screen package. The descriptions assume a certain amount of 
familiarity with progr amming problems and some finer points of C. None of it is terribly 
difficult, but you should be forewarned. 

4.1. Terminal Information 

In order to use a terminal’s features to the best of a program’s abilities, it must first know 
what they are 5 . The /etc/termcap database describes these, but a certain amount of decoding is 
necessary, and there are, of course, both effident and ineffident ways of reading them in. The 
algorithm that the uses is taken from vi and is hideously effident. It reads them in a tight loop 
into a set of variables whose names are two uppercase letters with some mnemonic value. For 


} Eye actually uses these functions. *1 does not. 

4 Graphics programs destined to run on character-oriented terminals. I could name many, but they come and 
jo. jo the list would be quickly out of date. Recently, there hive been pro trams such as rocket and run. 

3 If this comes as any surprise to you. there's this tower in Pans they're thinking of junking that I can let you 

have for a song. 
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example, HO is a string which moves the cursor to the ’home* position 6 . As there are two 
types of variables involving ttys, there are two routines. The first, gettmodeO , sets some vari¬ 
ables based upon the tty modes accessed by gtty(2) and stty(2) The second, seturmO , a larger 
task by reading in the descriptions from the /etc/termcap database. This is the way these rou¬ 
tines are used by iniacrO: 

if (isatty(O)) ( 
gettmodeO; 

if (sp-getenv(TERM’)) 
setterm(sp); 

) 

else 

setterm (Def_term); 

_puts(TI); 

juts (VS); 

isattyO checks to see if file descriptor 0 is a terminal 7 . If it is, gettmodeO sets the terminal 
description modes from a gtty(2) getenvO is then called to get the name of the terminal, and 
t tat value (if there is one) is passed to uttermO, which reads in the variables from 
/etc/termcap associated with that terminal. (getenvO returns a pointer to a string containing 
t^e name of the terminal, which we save in the character pointer sp.) If isattyO returns false, 
the default terminal Def_term is used. The 77and KSsequences initialize the terminal ( __putsO 
is a macro which uses tputsO (see termcap(3)) to put out a string). It is these things which 
endwinO undoes. 

4.2. Movement Optimizations, or. Getting Over Yonder 

Now that we have all this useful information, it would be nice to do something with it 6 . 
The most difficult thing to do properly is- motion optimization. When you consider how many 
different features various terminals have (tabs, backtabs, non-destructive space, home se¬ 
quences, absolute tabs, ) you can see that deeding how to get from here to there can be a 

decidedly non-trivial task. The editor vi uses many of these features, and the routines it uses 
to do this take up many pages of code. Fortunately, I was able to liberate them with the 
author’s permission, and use them here. 

After using gettmodeO and settermO to get the terminal descriptions, the function mvcurO 
deals with this task. It usage is simple: you simply tell it where you are now and where you 
want to go. For example 

mvcurfO, 0, LINES/2, COLS/2) 

would move the cursor from the home position (0, 0) to the middle of the screen. If you wish 
to force absolute addressing, you can use the function tgotoO from the termlib(7) routines, or 
you can tell mvcurO that you are impossibly far away, like Geveiand. For example, to abso¬ 
lutely address the lower left hand comer of the screen from anywhere just claim that you are in 
the upper right hand comer: 

mvcur(0, COLS-1, LINES-1, 0) 


* These names are identical to those variables used in the /atc/termcap database to describe each capability. See 
Appendix A for a complete list of those read, and tenncap(S) for a full description. 

1 aaayO is defined in the default C library function routines. It does a |try<2) on the descriptor and checks the 
return value. 

( Actually, it can be emotionally fulfilling just to get the information. This is usually only true, however, if you 
have the social life of a kumquat. 
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5. The Functions 

In the following definitions, “t” means that the “function’* is really a “#define” macro 
with arguments. This means that it will not show up in stack traces in the debugger, or, in the 
case of such functions as addchO , it will show up as it’s “w" counterpart. The arguments are 
given to show the order and type of each. Their names are not mandatory, just suggestive. 

5.1. Output Functions 


' addcfa(ch) T 
char ch; 

waddch(win, ch) 

WINDOW •win; 
char ch; 

Add the character ch on the window at the current (y, x) co-ordinates. If the character is 
a newline C\n') the line will be cleared to the end, and the current (y. x) co-ordinates will 
be changed to the beginning off the next line if newline mapping is on. or to the next line 
at the same x co-ordinate if it is off. A return (V) will move to the'beginning of the 
line on the window. Tabs (V) will, be expanded into spaces in the normal tabstop posi¬ 
tions of every eight characters. This returns ERR if it would cause the screen to scroll 
illegally. 


addstristr) t 

char m str; 

• 

waddstriwin, str) 

WINDOW •win; 
char 'str; 

Add the string pointed to by str on the window at the current (y, x) co-ordinates. This re¬ 
turns ERR if it would cause the screen to scroll illegally. In this case, it will put on as 
much as it can. 


box (win, vert, hor) 

WINDOW •win; 
ahar vert, hor; 

Draws a box around the window using vert as the character for drawing the vertical sides, 
and hor for drawing the horizontal lines. If scrolling is not allowed, and the window en¬ 
compasses the lower right-hand comer of the terminal, the comers are left blank to avoid 
a scroll. 


dearO t 

wdear(win) 

WINDOW •win; 

Resets the entire window to blanks. If win is a screen, this sets the dear flag, which will 
cause a dear-screen sequence to be sent on the next re fresh 0 call. This also moves the 
current (y, x) co-ordinates to (0, 0). 
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dearok (scr, boolf) t 

WINDOW 'scr; 
bool boolf; 

Sets the dear Qag for the screen scr. If boolf \s TRUE, this will force a dear-screen to be 
printed on the next refreshO, or stop it from doing so if boolf is FALSE This only works 
on screens, and, unlike clear() % does not alter the contents of the screen. If scr is cursor. 
the next refresh0 call will cause a dear-screen, even if the window passed to refreshO is 
not a screen. 


drtobotO t 

wdrtobot(win) 

WINDOW •wm; 

Wipes the window dear from the current (y, x) co-ordinates to the bottom. This does 
not force a dear-screen sequence on the next refresh under any drcumstances. This has 
no associated “m▼” command. 


drtoeolO t 

wdrtoeol(win) 

WINDOW %>in: 

Wipes the window dear from the current (y, x) co-ordinates to the end of the line. This 
has no assodated “tnv” command. 


delchO 

I 

wdelch(win) 

WINDOW *wirt; 

Ddete the character at the current (y. x) co-ordinates. Each character after it on the line 
shifts to the left, and the last character becomes blank. 


deletelnO 

wdeleteln(win) 

WINDOW 'win; 

Delete the cunent line. Every line bdow the current one will move up, and the bottom 
line will become blank. The current (y, x) co-ordinates will remain unchanged. 


eraseO T 


we rase (win) 
WINDOW Sr in; 


Screen Package 


Erases the window to blanks without setting the clear flag. This is analagous to dearO, 
except that it never causes a dear-screen sequence to be generated on a refreshO. This 
has no assodated "mv" command. 


insch(c) 
char c; 


winsch(win, c) 

WINDOW *wm; 
char c; 

Insen c at the current (y, x) co-ordinates Each character after it shifts to the right, and 
the last character disappears. 


insertln 0 

winsertin(win) 

WINDOW *win; 

Insen a line above the current one. Every line below the current line will be shifted 
down, and the bottom line will disappear. The current line will become blank, and the 
current (y, x) co-ordinates will remain unchanged. 


1tnove(y, x) t 
ini y, x; 

wmov«(win, y, x) 

WINDOW *win; 

int y, x: * 

Change the current (y, x) co-ordinates of the window to (y, x). This returns ERR if it 
would cause the screen to scroll illegally. 


overlay (win 1, win2) 

WINDOW •* ini. *win2; 

Overlay winl on win2. The contents of w ini, insofar as they fit, are placed on w in2 at 
their starting (y, x) co-ordinates. This is done non-destructiveiy, i.e., blanks on win1 
leave the contents of the space on w in2 untouched. 


overwrite (winl, win2) 

WINDOW *winl, *win2; 

Overwrite wini on win2. The contents of wini, insofar as they fit, are placed on win2 at 
their starting (y, x) co-ordinates. This is done destructively, i.e., blanks on wini become 
blank on w in2. 


printw(fmt, argl, arg2, ...) 
char *fmt: 


Screen Package 


wprintw(win, fmt, argl« arg2,...) 

WINDOW •win; 
char *fmt; 

Performs a printfO on the window starting at the current (y, x) co-ordinates. It uses 
addstrO to add the string on the window. It is often advisable to use the field width op¬ 
tions of printfO to avoid leaving things on the window from earlier calls. This returns 
ERR if it would cause the screen to scroll illegally. 


refresh 0 t 


wTefresh(win) 
WINDOW •win; 


Synchronize the terminal screen with the desired window. If the window is not a screen, 
only that part covered by it is updated. This returns ERR if it would cause the screen to 
scroll illegally. In this case, it will update whatever it can without causing the scroll. 


standoutO T 

wstandout(win) 
WINDOW •win; 


standendO t 


wstandend(win) 

WIN DO W V/n; 

Stan and stop putting characters onto win in standout mode. standourO causes any charac¬ 
ters added to the window to be put in standout mode on the terminal (if « has that capa- 
ttlity ) landendO stops this. The sequences 50 and SE (or US and UE if they are not 
defined) are used (see Appendix A). 


5.2. Input Functions 


cnnodeO t 
nocrmodeO t 

Set or unset the terminal to/from cbreak mode. 

echoO t 
noecho0 t 

Sets the terminal to echo or not echo characters. 
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